Developer CD Series 1990: Night of the Living Disc/Night of the Living Disc.2mg/Dev.CD.5/Tools/Documents/STYLE.GUIDE.P1

Text File | 1989-03-21 | 129.2 KB | 4,773 lines | [04] ASCII Text (0x0000)

ar    Apple Publications

    Style Guide

    January 1989



a APPLE COMPUTER, INC.

Copyright c 1989 by Apple Computer, Inc.



All rights reserved. No part of this publication may be reproduced, stored in a retrieval
system, or transmitted, in any form or by any means, mechanical, electronic,
photocopying, recording, or otherwise, without prior written permission of Apple
Computer, Inc.



Apple, the Apple logo, AppleTalk, Apple IIgs, AppleShare, A/UX,  AppleWorks,
HyperCard, ImageWriter, LaserWriter, Macintosh, and ProDOS are registered
trademarks of Apple Computer, Inc.



APDA, Apple Desktop Bus, AppleMouse, Apple Writer, EtherTalk, Finder, and
LocalTalk are trademarks of Apple Computer, Inc.



CLARIS is a trademark of CLARIS Corporation.



CP/M is a registered trademark of Digital Research, Inc.



Ethernet is a registered trademark of Xerox Corporation.



PostScript is a registered trademark of Adobe Systems, Incorporated.



ITC Avant Garde Gothic, ITC Garamond, and ITC Zapf Dingbats are registered
trademarks of International Typeface Corporation.



Microsoft and MS-DOS are registered trademarks of Microsoft Corporation.



NuBus is a trademark of Texas Instruments.



PC-DOS is a registered trademark of International Business Machines Corporation.



UNIX is a registered trademark of AT&T Information Systems.



Contents



Figures and tables  iv

Apple trademarks  v



    About This Guide  vii



What's in this guide  viii

Conventions used in this guide  viii

Related publications  ix



    Style and Usage1





Appendix A

Technical Notation 101



General considerations  102

Code  102

Syntax descriptions  103

Computer voice in text  104

Metasymbols in text  106



Appendix B

Units of Measurement  107



Figures and tables



Figure 1    An alert box  3

Figure 2    An arrow pointer  7

Figure 3    Buttons  12

Figure 4    Check boxes  16

Figure 5    Command keys on various keyboards  19

Figure 6    Command names in a pull-down menu  20

Figure 7    Crossbar pointers  23

Figure 8    A crosshair pointer  23

Figure 9    A dialog box  28

Figure 10    Dimmed icons and menu commands  29

Figure 11    A directory dialog box  29

Figure 12    An I-beam pointer  46

Figure 13    Indicators in a hierarchical menu  50

Figure 14    Menu commands in a pull-down menu  65

Figure 15    Mini-windows  66

Figure 16    Pointers  75

Figure 17    Radio buttons  81

Figure 18    A menu and a submenu  88

Figure 19    The System file icon  89

Figure 20    The System Folder icon  89

Figure 21    A tear-off menu  92



Table 1    How to form a manual title: User manuals  63

Table 2    How to form a manual title: Technical manuals  63

Table 3    How to form a manual title: Pocket guides  63

Table 4    How to generate curly quotation marks  81

Table 5    Abbreviations for state names  87



Apple trademarks



Many trademarked Apple product names appear in this guide. In an actual manual, the
appropriate trademark symbols would be used on first occurrence of the product name in
the text. Because this guide is a random-access document, however, there is no way to
predict which occurrence of a term the reader will encounter first. For that reason, all
Apple trademarks mentioned in the guide are listed below, with the appropriate
trademark symbols.



APDAt

Apple Desktop Bust interface

AppleMouset mouse device

AppleSharer file server

AppleTalkr network system

Apple IIgsr computer

AppleWorksr software

Apple Writert application program

A/UXroperating system

EtherTalkt interface card

Findert interface

HyperCardr software

ImageWriterr printer

LaserWriterr printer

LocalTalkt cable system

Macintoshr computer

MacProjectr application program

MacTerminalr application program

MacWriter application program

ProDOSr operating system

P    R    E    F    A    C    E



About This Guide



THE APPLE PUBLICATIONS STYLE GUIDE IS FOR WRITERS, EDITORS,

proofreaders, and others who work on Apple manuals, product training
disks, and on-line instructional and reference materials. Outside
developers of Apple-related products may also find some parts of this
guide useful.





What's in this guide



This guide is designed as a random-access reference tool, though some
users, such as editors and proofreaders, may want to familiarize
themselves with the entire document.

"Style and Usage" shows how certain terms are used in Apple
publications and gives preferred style (capitalization, spelling, and
hyphenation) for those terms. It also gives general rules of style and usage
for Apple publications. Entries are listed in alphabetical order.

The appendixes cover special topics that may be useful to those working
on Apple publications.



n    Appendix A, "Technical Notation," gives special style and usage rules
that apply largely or exclusively to technical manuals. (These rules are
also included by topic in  "Style and Usage.")

n    Appendix B, "Units of Measurement," gives preferred style for
spelled-out and abbreviated forms of units of measurement likely to occur
in Apple publications.





Conventions used in this guide



Except in special cases described in this guide, follow the style and usage
rules in The American Heritage Dictionary, The Chicago Manual of Style,
and Words Into Type. In cases where these reference books give
conflicting rules, follow The Chicago Manual of Style for questions of
usage and The American Heritage Dictionary for questions of spelling.

An entry followed by adj. in parentheses gives the form to be used when
the adjective precedes the noun it modifies.

An entry followed by pred. adj. in parentheses gives the form to be used
when the adjective is a predicate adjective (that is, when the adjective
follows the noun it modifies).

















































Related publications



In addition to the Apple Publications Style Guide, publication groups
within Apple Product Marketing publish the following documents:



n    Apple Publications Glossary, which gives guidelines for creating a
glossary for an Apple manual and provides an extensive list of glossary
entries that can be adapted or used verbatim in any Apple manual (also
available on disk, so that writers can copy and paste entries to suit the
needs of their manuals)



n    The Editorial Process, which describes the route a manual or disk
follows from the time it is first submitted to the Editorial Group until it is
handed off to the Production Group (in the case of a manual) or is ready
for duplication in its final form (in the case of a disk)



n    The Production Process, which describes the stages of production for
manuals and includes guidelines for writers on highlighting a manuscript
for the indexer



Design specifications are also available from art managers and art directors
in publication groups. These documents describe the design elements for
Apple manuals. Examples of these are the Galaxy design specs (for CPU
and peripheral books), and Nova design specs (for the Apple Technical
Library, etc.).

If you need a copy of any of these documents or additional copies of the
Apple Publications Style Guide, or if you want to contribute suggestions
or corrections for any of the documents, you can contact the Developer
hotline.























































Style and Usage



abbreviations and acronymsAn acronym is a pronounceable word formed from the
initial letter or letters of major parts of a compound term. An abbreviation is usually
formed in the same way but is not pronounced as a word. Acronyms are always all
caps, regardless of the capitalization style of the spelled-out form.

    Abbreviation: bps-for bits per second

    Acronym: BASIC-for Beginners All-purpose Symbolic Instruction Code



Always spell out an abbreviation or acronym on first occurrence, and define it if its
meaning isn't self-evident. (In some cases, such as reference manuals that will not
likely be read sequentially, you may want to repeat the spelled-out form on first
occurrence in each chapter or major section.) Give a pronunciation key for acronyms if
the pronunciation is not self-evident.



    SCSI (pronounced "SKUH-zee")



Don't use periods except in abbreviations for English (nonmetric) units of measurement
or in the abbreviations U.S., a.m., and p.m. Don't add an apostrophe before the s when
forming the plural.



    ICs, RAMs, ROMs



For the rules on forming the plural of letters, characters, and symbols, see plurals.



Don't use the Latin abbreviations e.g., etc., or i.e. Instead, use for example, and others,
and that is, or equivalent phrases in English.



For abbreviations of units of measurement, see Appendix B, "Units of Measurement."



For abbreviations of state names, see Table 5 under state names.



able (suffix)When adding -able to a word ending in e, drop the e unless it is preceded
by a soft c or a soft g.



    browsable, deletable, sharable, sizable

    changeable, pronounceable, purgeable



abortDon't use when you mean cancel.























aboveDon't use to describe an element that has already occurred in a manual. Use a
more specific reference, such as earlier in this chapter. For a chapter or a section,
include the chapter or section title. For a figure or a table, include the number of the
figure or table.



    For more information, see "Printing" earlier in this chapter.



    For a summary of slot and drive numbers, see Table 1-2 earlier in this chapter.



accessAvoid as a verb where possible, especially in user manuals. Even in technical
manuals, consider more precise alternatives (for example, log on to).



accessoryUse accessory only for actual accessories such as carrying cases and mouse
pads, not for peripheral devices. Don't use accessory device. Compare desk
accessories; device.



accessory access portDon't use; use SE Bus access port.



accessory slotDon't use; use expansion slot.



adapterNot adaptor.



addressSee memory address, memory location.



affect (v.),effect (n., v.)

    Affect (v.): The change in format affects [influences] only the text you've selected.



    Effect (n.): Command-H has no effect [result] on any other  window.



    Effect (v.): Command-H effects [brings about] a change.



afterwardNot afterwards.



alertRefers generically to a signal, either visual (an alert box) or auditory (a beep), that
calls the user's attention to an unusual situation. Don't use alert when you can use the
more specific alert box.



alert boxRefers to a type of dialog box, like the one shown in Figure 1, to which the
user can respond only by clicking a button (such as OK or Cancel) or by pressing Enter
or Return. Compare dialog box.

n    Figure1    An alert box





MSC 1

ART: 14 x5 pi

8.5 pi text to FN b/b





alert messageRefers to a message presented inside an alert box or on the screen. OK
in technical manuals; otherwise, use just message.



allowDon't use allow when you mean enable. (In general, hardware enables;
software allows.) Compare enable.



    Correct: MacTerminal allows you to transmit data.



    Incorrect: MacTerminal enables you to transmit data.

Avoid using allow when you can restructure a sentence so that the reader is the
subject.



    Correct: AppleWorks allows you to create a database.



    Preferable: With AppleWorks you can create a database.



allrightNot alright.



alphabeticNot alphabetical, except when referring specifically to alphabetical order.
(Exception to American Heritage.)



alphabetizationAlphabetize letter by letter, not word by word.

    program disk

    programmer

    program selector



alphanumericOne word.



alrightDon't use; use all right.



a.m.Note small caps and periods. (Exception to the rule that abbreviations do not
include periods.)



ampersandUse the ampersand character (&) in text only when describing a command
name or other on-screen element that uses the character. In all other cases (such as when
citing a disk or manual title that uses the ampersand character) use the word and.



and/orRewrite to avoid this construction.



angle bracketsUse angle brackets, not brackets, to describe these symbols: < >.
When you need to distinguish between the two angle brackets, use left angle bracket
and right angle bracket. Don't confuse with the caret (^). You can also use less-than
sign and greater-than sign for these symbols if appropriate in the context.



ANSIAcronym for AmericanNationalStandardsInstitute. Spell out on first occurrence.



anti (prefix)Close up except before i, a proper noun, or a proper adjective. (Hyphenate
in those cases.)



anytime (adv.)Not any time, except in the construction at any time.



APDAFormerly an acronym for Apple Programmers and Developers Association. The
acronym is a trademark of Apple Computer, Inc. Spell out on first occurrence except in
the boilerplate copy.



apostropheUse the curly apostrophe (generated by pressing Option-Shift-] ) except in
computer voice. See also plurals; possessives; quotation marks.



appendix  Use appendixes for background information and other supplementary
material that does not contribute directly to the main tasks being taught in the manual.
In owner's guides and user's guides technical information should go in an appendix.

Chapters are numbered; appendixes are lettered.

The first appendix (Appendix A) begins on a right-hand page unless it is preceded by an
appendix part title. Subsequent appendixes can begin on a right-hand or left-hand page.

An appendix part title may precede the first appendix and includes only the word
Appendixes. It is always on a right-hand page.

When a book has only one appendix, refer to the appendix as Appendix, not Appendix
A. Cross-references to a single appendix should refer to the Appendix.



appendixesNot appendices.



ApplekeyDon't use; use Command key for the key on Apple II and Macintosh
computers (see Figure 5) that is marked with an Apple symbol, a propeller symbol, or
both. (On Apple II-family keyboards that have two keys with Apple symbols, the key
marked with an open Apple is now the Command key; the key marked with a solid
Apple is now called the Option key.)

If your manual might be read by users who are familiar with the term Apple key, it's a
good idea to explain the change in terminology.



Apple Programmers and Developers Association (APDA)Spell out on first
occurrence except in the boilerplate copy. The acronym is a trademark of Apple
Computer, Inc.



AppleTalkRefers to an overall network system and any software that supports it,
including the resources you turn on and off in the Chooser. For clarity, it's preferable
to refer to an AppleTalk network system rather than just an AppleTalk network. The
short form AppleTalk system is acceptable, however. Don't use AppleTalk Personal
Network.

In addition to AppleTalk network system, the following terms are appropriate uses of
the word AppleTalk: AppleTalk developer, AppleTalk identification number, AppleTalk
network architecture, AppleTalk software, and AppleTalk zone.

Don't use AppleTalk printer or AppleTalk device; instead, use network printer or
network device.

Shared devices used over an AppleTalk network system, such as an AppleShare file
server or a shared LaserWriter printer, can be called AppleTalk services.

See also Ethernet; EtherTalk; LocalTalk.



AppleIIc, AppleIIe, Apple IIgsUse with the noun computer on first occurrence
in each major section (that is, preface, chapter, appendix, and so on). Add the r symbol
on first occurrence both in the preface and in the text. Note that Apple IIgs as a unit is
a registered trademark, but that Apple IIc and Apple IIe take the mark only if it's the
first use of Apple. (Thus the names and marks would appear as Apple IIgsr, Appler
IIc, and Appler IIe.)

To avoid confusion, don't use Apple II to refer to a specific machine, unless you really
mean the old Apple II. (It's fine to use Apple II when giving information that applies
to all members of the Apple II family.) Don't use Apple computer except when
referring globally to all computers (Apple II family and Macintosh family) produced by
Apple Computer, Inc.

The numeral II in any Apple II product name is not italicized or formed with brackets or
slashes.

    Correct: Apple IIe

    Incorrect: Apple IIe, Apple ][e, Apple //e

When forming the plural, use Apple IIc computers (or Apple IIe computers or
Apple IIgs computers). Rewrite to avoid using the possessive form of any of these
computers.

The letters g and s in Apple IIgs are small caps.

See also standard Apple II.



Apple IIgs Programmer's Workshop (APW)Not Apple Programmer's
Workshop or Apple IIgs Programmers' Workshop. Spell out on first occurrence.



AppleIIPlusNo hyphen. Don't use a plus sign (+).

applicationUse application program on first mention; thereafter, use application.
Don't use software program.



applicationsoftwareNot applicationssoftware. Use only when referring to
application software in general; use application program or application when referring
to a single program.

APWAbbreviation for Apple IIgs Programmer's Workshop. Spell out on first
occurrence.

APW Assembler, Compiler, Editor, LinkerUse the full name on first mention:
APW Assembler. Thereafter, you can use the short form, which is lowercase: the
assembler.

n    Figure 2An arrow pointer





arrowUse pointer in general references; use arrow or arrow pointer when describing
the specific type of pointer shown in Figure 2.

    The pointer becomes an arrow [or I-beam, or crossbar, and so on ].



arrowheadOne word. Don't use when you mean the tip of the arrow pointer.



arrowkeysUse lowercase in general references. Don't use direction keys. The name of
each arrow key is capitalized.

    Use the arrow keys to move the cursor from cell to cell.

    Press the Left Arrow key.



ASCIIAcronym for AmericanStandard Code for Information Interchange. Spell out on
first occurrence.



assemblerCapitalize assembler only when using the full name: the APW
Assembler, but the assembler. Don't use assembler when you mean assembly
language.



assemblylanguage (n.), assembly-language (adj.)Not assemblerlanguage. Note
hyphenation of adjective.



assembly time (n.), assembly-time (adj.)Note hyphenation of adjective.



assureDon't use when you mean ensure.



authorized Apple dealerNot dealership or Apple-authorized dealer. Don't shorten to
dealer except in passages where using the full term becomes cumbersome or overly
repetitive.



auto-key (adj.)Note hyphenation.



auto-repeat (n., adj.)Note hyphenation.



A/UXNote slash. Use in references to Apple's version of the UNIX operating system.
Don't use Apple UNIX or Apple's UNIX system. Compare UNIX system.



auxiliaryNot auxilliary.



auxiliaryslotRefers to a special slot in the Apple IIe for the Apple IIe 80-Column
Text Card or the Apple IIe Extended 80-Column Text Card. Labeled
AUX.CONNECTOR on the main logic board. Don't use videoslot or video connector.



back matter  Back matter includes any sections that follow the main text of a
manual-appendixes, glossary, bibliography, and index. Depending on the size of your
manual and its audience, you may not need to include back matter at all, or you may
need to include only some of the possible sections.  See appendix, bibliography,
glossary, index.



backpanelTwo words. Not backplane.



backslashOne word.



backspace (n., v., adj.)One word.



BackspaceThe key. Note capitalization.



backup (n., adj.), backup (v.)No hyphen. (Exception to American Heritage.)



backward (adv.)Not backwards when referring to direction. But in certain other
contexts, such as putting a garment on backwards, it's OK to use backwards.



ballot boxDon't use; use check box.



ball-pointpenNote hyphenation.



BASICAcronym for Beginners All-purposeSymbolic InstructionCode. No apostrophe
in Beginners; lowercase p in purpose. Spell out on first occurrence.



baudNote lowercase. Baud is often used interchangeably with bits per second, but they
are not necessarily the same; see the entry under baud in the Apple Publications
Glossary.



baud rate OK to use to mean data transmission rate.

    The two computers must be set to the same baud rate to transmit data correctly.



Beginners All-purpose Symbolic Instruction Code (BASIC)No apostrophe
in Beginners; lowercase p in purpose. Spell out on first occurrence.



belowDon't use to describe an element that has not yet occurred in a manual. If
necessary, use a more specific reference, such as later in this chapter. For a chapter
or a section, include the chapter or section title. For a figure or a table, include the
number of the figure or table.

    For more information, see "Printing" later in this chapter.

    For a summary of slot and drive numbers, see Table 3-2 later in this chapter.



bibliography  Don't include a bibliography unless it serves a very specific purpose.
If you have relied on printed sources other than Apple manuals in writing your manual,
you should credit those sources in a bibliography.

If the scope of your manual is limited but you feel that many readers may want to seek
out more information on their own, a bibliography can also be useful. (In a printer
manual, for example, it might be helpful to include some suggestions for further
reading in the field of desktop publishing; such material might best be handled as a
bibliographic section at the end of the relevant chapter, however, rather than in a full
bibliography in the back matter.)

The bibliography always begins on a new page.



bibliographyentriesIn each entry, invert the first author's name (last name first,
with a comma both before and after the first name or names). Italicize book and
periodical titles. Enclose article titles in quotation marks. Don't give the name of the
state or country when the place of publication is a well-known city. If you need to
provide a state name, use the correct postal abbreviation, given in Table 5 under state
names.

    Book:    Norman, Donald A., and David E. Rumelhart.    Explorations in Cognition.
San Francisco:     W. H. Freeman, 1975.

    Article:    Sculley, John. "Why We Need a Counterbalance."     Personal Computing,
October 1986, 280-283.

For rules on bibliographic citation of other kinds of material, refer to The Chicago
Manual of Style.



bitDon't use when you mean pixel or a dot on the screen.



bitmap (n., v.), bitmapped (adj.), bitmapping (n.)One word in all forms.



bits per second (bps)Not the same as baud; see the entry under baud in the Apple
Publications Glossary. Spell out on first occurrence.



black-and-white (adj.), black and white (pred. adj.)

    She's writing about the black-and-white monitor.

    The image on the screen is black and white.

For screens, monochrome is usually more appropriate because it encompasses amber
and black, green and black, and so on.



blank characterDon't use; use space character.

blinkingUse to describe the insertion point (Macintosh) or the cursor (Apple II).
Don't use flashing for this purpose.



boardDon't use when you mean card. A board is built in; a card can be removed
by the user.



boldfaceIn manuals, use only for new terms on first occurrence with definition. If the
term is defined in a marginal gloss, boldface the term in the gloss as well. In tour
disks, use for words the user types. Use italics, not boldface, for emphasis in manuals,
but don't overdo it!   Generally, new terms in a manual should also be listed in the
glossary.



bombDon't use as a verb, but bomb is OK as an adjective, as in the bomb icon.



book designs  The designs of Apple's customer and technical publications are
maintained by design specialists on the art staff of each writing group. Consult these
people for answers to theoretical or practical questions about book design.

As Apple's markets have grown and become more differentiated, the kinds of book
designs available to writers have become more specialized. For some time, customer
and technical publications both used variants of the Grand Design, which is gradually
being phased out at the time of this writing. While the designers have worked to
maintain a consistent "feel" across all Apple books, they have also made sure that the
new designs are appropriate for the books' content.

Customer publications, which tend to be teaching tools and require an open,
unintimidating look, are now being prepared in the Galaxy design. This design uses
fairly short lines of text, second-level heads in the margin, and lots of white space to
make the books easier for first-time computer owners to use. The Apple Publications
Style Guide is in the Galaxy design.

Technical publications, which tend to be used for reference (and thus need to be more
book-like), are now being prepared in the Nova design. This design has more of the
features of traditional reference books.

Both Galaxy and Nova are standard designs intended to be customized, which means that
new design elements can be provided on request. If some aspect of your manual requires
special treatment that doesn't seem to be available within the framework of the existing
design elements, consult your art director about the possibility of creating a new
element.

It's usually a good idea to explain in the preface of your manual the conventions you
have followed in using design elements such as incidental boxes, tag boxes, and
marginal glosses. The use of fonts and styles for special purposes (such as Courier for
computer voice and boldface for new, defined terms) should also be explained in the
preface.

Most text in any manual should be main text; overuse of special text elements (bulleted
and numbered lists, tag boxes, incidental boxes, and marginal glosses) diminishes the
impact of those elements, makes for a cluttered page, and hinders the reader's
comprehension.

Sample pages, detailed design specifications, and functional definitions of all existing
elements are provided in the documents that describe the Galaxy and Nova designs. For
more information, see these documents, or consult an art director, a project editor, or a
developmental editor.



Boolean(adj.)Note capitalization.



bootDon't use for startup or switch on in user manuals. In manuals written for new
users, however, you may want to mention the term boot or include it in your glossary
because users may see it elsewhere.



boot diskDon't use except in technical documents; use startup disk.



bottom leftAvoid; use lower left as a noun, lower-left as an adjective.



bottom rightAvoid; use lower right as a noun, lower-right as an adjective.



bpsAbbreviation for bits per second. Spell out on first occurrence.



braces ( { } )Not curlybrackets, but it's OK to define braces as curly brackets on first
mention. When you need to distinguish between the two braces, use left brace and right
brace.



brackets ( [ ] )Not square brackets. But don't use brackets when you mean angle
brackets (< >). When you need to distinguish between the two brackets, use left bracket
and right bracket.



Browse toolNote capitalization.



built-in (adj.), built in (pred. adj.)Hyphenate only before the noun.

    The dialog box shows the name of the disk in the built-in drive.

    The 3.5-inch disk drive is built in.



built-in disk driveUse either built-in disk drive or internal disk drive to match the
software.



bus, busesNote spelling of plural.



n    Figure 3    Buttons

MSC 3

buttonYou click an on-screen button; you press a mechanical button. (Figure 3 shows
two kinds of on-screen buttons.) Capitalize names of rounded-rectangle buttons as you
would a title.

    Click Cancel.

    Click the Connect to Network button.

    Press the mouse button.

See also click.



button on the hand control, hand-control buttonNot paddle button.



Button toolNote capitalization.



cableUse cable to describe what physically connects two pieces of hardware. Don't use
cabling even when you mean cable collectively. Compare cord.



cable extender, cable terminatorUse lowercase even when using the full product
name: LocalTalk cable extender, SCSI cable terminator.



cache (n., v.), cached (v.), caching (n., v.)Note spelling. See also RAM cache.



CalculatorThe desk accessory. Note capitalization.



call (a program)Don't use when you mean load.



calloutsUse a callout (a short text label with a line that points to part of a figure)
whenever you need to identify something within a figure. Callouts are usually
positioned outside the boundaries of the figure (especially when the figure is a
photograph or a screen shot), and a thin line without an arrowhead, known as a leader
line, connects the callout to what it identifies within the figure.

Use callouts freely when they are really necessary, but keep in mind that too many
callouts can be distracting to the reader. Don't use callouts when a clearer caption would
make the point just as well. Keep callouts brief, both for clarity and for an uncluttered
look.

If a figure requires callouts, don't place it in the margin. Because such figures are small
and have little space around them, callouts are usually difficult or impossible to
position with figures in the margin.

Capitalization style for callouts is initial cap only. Don't use a period, even if the
callout is a complete sentence. (If a callout contains two sentences, rewrite it.) Avoid
using computer voice, boldface, or italics in callouts whenever possible.

If you use fractions in a callout, use kerned fractions rather than fractions with both
numerator and denominator on the line.



cancelIn technical manuals, an unconditional, permanent halt that carries the
connotation of undoing something. OK to use cancel instead of halt to avoid
awkwardness. In a dialog box in the desktop interface, Cancel (note capitalization) is a
button option the user clicks when he or she doesn't want to proceed with a particular
action. Compare abort; exit; halt; interrupt; stop.



Cancel buttonNote capitalization.



canceled, cancelingNot cancelled, cancelling.



capitalization

    all caps

    THIS LINE IS AN EXAMPLE OF ALL CAPS.

Don't use all caps for emphasis. Use italics in manuals; use underlining in training
disks if available (otherwise, all caps is acceptable).

    caps/lowercase

    This Line Is an Example of Caps/Lowercase.

Use caps/lowercase for book titles, part titles, chapter titles, disk titles, titles of major
sections of disks, running feet that use chapter titles, and cross-references to book, part,
chapter, and section titles.

In cross-references to a specific appendix or chapter or to the preface, capitalize the word
Appendix, Chapter, or Preface. But when referring to appendixes, chapters, or prefaces
in general, do not capitalize the word appendix, chapter, or preface.

    See the Preface for more information.

    See the Appendix for a list of specifications.

    The preface of a manual is a good place to explain the typographic conventions you
follow in the text.

In cross-references to sections that never take a title (glossary, index, table of contents,
and so on), don't capitalize the name of the section.

Follow these rules when using caps/lowercase:

n    Capitalize every word except articles, coordinating conjunctions, to in infinitives,
and prepositions of three letters or fewer (except when a preposition is part of a verb
phrase).

    Switching On the Computer

    Introduction to the Apple IIgs

    How to Start Your Printer

    Getting Started With Your Macintosh II

n    Capitalize the first and last word, no matter what their part of speech.

    Of Mice and Men

    The Rules We Fail to Live By

n    Capitalize the second word in a hyphenated compound.

    Correct: High-ResolutionGraphics

    Incorrect: High-resolutionGraphics

    Exception: Built-inDiskDrive

n    Capitalize Is, It, Than, That, and This.

    initial cap only

    This line is an example of initial cap only.

Use initial cap only for all levels of heads, for figure and table captions, for callouts,
for running feet that use section titles, for tag words in tag boxes, and for italic lead-in
lines in incidental boxes.

Don't use initial cap only in cross-references to section heads; use caps/lowercase.

When using initial cap only, capitalize only the first letter of the first word, as well as
the first letter of any proper nouns and proper adjectives.

Caps LockThe key. Not Shiftlock. Note capitalization.



captionsSee "Figure Captions" and "Table Captions" in Chapter2.



cardRefers to a removable circuit board that is installed in a slot. Compare board. See
also controllercard; interfacecard; memory expansion card;
peripheralcard.



cardnamesCapitalize the product name, including card. When using generically, don't
capitalize: 80-columntextcard when referring to any 80-column text card, but the
AppleIIe 80-Column TextCard. Some cards, such as the AppleMouse II controller card,
are not separate products, however; don't capitalize card in such cases.



caretDon't use when you mean circumflex. A caret (^) is used, for example, to mark a
dynamic variable in Pascal; a circumflex (e) is an accent used, for example, in the
French verb etre. Don't confuse with the angle bracket.



carriage return (CR)Use when referring to ASCII character $0D or its equivalent.
Spell out on first occurrence. Use return character when writing about, for example,
searches for return characters. Use Return key for the key you press. Explain the term
Return key if your manual is for first-time computer users.



catalogUse as a noun only in references to the DOS operating system; otherwise, use
directory.

cathode-ray tube (CRT)Note hyphenation. Spell out on first occurrence. Don't use
when you mean monitor or screen.



CDAbbreviation for compact disc. Spell out on first occurrence.



CD-ROMNote hyphenation and capitalization. Don't shorten to CD.



cellDon't use when you mean memory address or memory location.



centralmemoryDon't use; use mainmemory.



centralprocessing unit (CPU)Spell out on first occurrence. Meaningful only in
contrast with peripheral processor. Don't use when referring to the whole computer. In
manuals written for new users, however, you may want to mention this (mis)use of
CPU because users may see it elsewhere. Never refer to the central processing unit as
the unit. See also main unit.



chapterCapitalize the word chapter in references to specific chapters.

    Chapter5, "Expanding Your Macintosh SE"

    Chapters4 and5

    in the next chapter

Use caps/lowercase for chapter titles. (See capitalization for guidelines on using
caps/lowercase.)



chapter opener  You should generally plan on including a paragraph (approximately)
of chapter-opening text for all sections (including the preface and appendixes). This
material will introduce the chapter to your reader.



chapter tables of contents  Use tables of contents before each chapter only in very
long manuals (such as Inside Macintosh) where the main table of contents in the front
matter is unmanageable as a locator for sections throughout the entire book. If you use
chapter tables of contents, use them for every chapter.

The format of the chapter tables of contents is identical to that of the main table of
contents, except that level-one heads replace chapter titles, level-two heads replace
level-one heads, and so on. In a book with chapter tables of contents, it's a good idea to
eliminate level-four heads from the main table of contents; the reader will most likely
consult the chapter tables of contents to locate topics at that level of detail.



characterUse in reference to what a key on the computer's keyboard stands for.
Compare symbol.



character positionUse in describing a system that uses pixels for character
formation and placement. Compare column; row.



checkDon't use when you mean the action of clicking a check box to select an option.



Fig4



check boxRefers to an on-screen box like the ones shown in Figure 4. Two words;
note lowercase. Not box or ballot box. You click a check box to select or deselect an
option; you don't check or uncheck a check box. See also button; radio button.



chipUse integratedcircuit or siliconchip (with an explanation of the term) on first
occurrence.





chooseUse choose, not select, for menu commands. In general, the user selects
something (such as a disk icon, a graphic image, or a section of text) and then chooses
a command to act on the selection.

For tear-off menus that become palettes, choose is still appropriate. See also select.

    Correct: Choose Paste from the Edit menu.

    Incorrect: Select Paste from the Edit menu.

    Incorrect: Choose the icon that represents your document.

ChooserThe desk accessory. Note capitalization.



circuit board (n.)No hyphen.



circumflexDon't use when you mean caret. A circumflex (e) is an accent used, for
example, in the French verb etre; a caret (^) is used, for example, to mark a dynamic
variable in Pascal.



CLARIS CorporationUse all caps (not small caps) for the word CLARIS. When
using the full name of the corporation, spell out Corporation.



clickOn first occurrence, describe the action of positioning the pointer on an object
and briefly pressing and releasing the mouse button. (You don't click the mouse
button, you press it.) After that, simply refer to the object to be clicked.

    Icon: Click the disk icon.

    Button: Click Cancel.

    Check box: Click Auto Page Numbering.

See also click in; click on.



click and dragDon't use. You either click or drag.

    Correct: Drag the icon to the Trash.

    Correct: Click the icon to select it and then drag it to the Trash.

    Incorrect: Click and drag the icon to the Trash.



click inYou click in a window; you click all other on-screen elements, such as icons,
check boxes, and buttons.



click onDon't use; use click.



ClipboardThe desk accessory. Note capitalization.

closeYou close a window or a document. Don't refer to an icon as a closed window.
See also open.



close boxNote lowercase. Not go-away box or save box.



Closed Apple keyDon't use; use Option key for the key marked with a solid Apple
on Apple II-family keyboards that have two keys with Apple symbols.

If your manual may be read by users who are familiar with the term Solid Apple key,
it's a good idea to explain the change in terminology.



close regionDon't use; use go-away region.



CLUTAcronym for color look-up table. Spell out on first occurrence.



codeUse computer voice for code.

If the language you're working with has a standard style of indentation, use it. If it
doesn't have such a style, develop a logical method of your own and use it consistently.

    WHILE i<63 DO    BEGIN        IF odd(i) THEN z := z*w        ELSE z := y    END

Develop a method of spacing around punctuation and use it consistently. It's often best
to use "English-style" spacing because it's easy to remember and stick with.

    (height, width: extended; quo: integer);PageSize = 1024

code fileTwo words, except in reference to the Pascal predefined file type codefile.



code namesUse exactly the same form for a product's code name throughout a manual
or product training disk. (If the name is sometimes misspelled or otherwise treated
inconsistently, a global search-and-replace is not possible.)



coldstart (n., v.), cold-start (adj.)Not coldstart.



colonsAvoid using colons in text heads; if it is absolutely necessary to use a colon in
a head, capitalize the first word after the colon.



colophon  All Apple manuals must have a colophon, which goes on the inside back
cover. The colophon is standard text identifying some of the equipment and some of the
design conventions used to produce Apple manuals.

The colophon is a boilerplate element; see the boilerplate folder on your departmental
file server to get a disk copy of the appropriate colophon for your manual.

If your manual includes computer-generated or scanned line art, or if it will be produced
with tools other than those listed in the colophon, you may need to revise the colophon
and the copyright page to include the appropriate credit lines.



color look-up table (CLUT)Note lowercase and hyphenation. Spell out on first
occurrence.



columnUse in describing a system that uses a grid of vertical columns and horizontal
rows for placement of characters on the screen. Compare character position.



commandUse instead of menu option or menu item when describing the desktop
interface in user manuals.

    The menu contains a list of commands.

    Use the Save command to save any changes to your file.



Command keyNot Apple key, Open Apple key, or Hollow Apple key. The key on
Apple II and Macintosh computers that is marked with a propeller symbol, an Apple
symbol, or both. (On Apple II-family keyboards that have two keys with Apple
symbols, the key marked with an open Apple is now the Command key; the key
marked with a solid Apple is now called the Option key.) Figure 5 shows Command
keys on various keyboards. Be sure to explain the variants to your readers.

If your manual may be read by users familiar with the term Apple key or Open Apple
key, it's a good idea to explain the change in terminology.

n    Figure 5    Command keys on various keyboards









MSC 1

ART: 25 x 9.5 pi

13 pi text to FN b/b







commandnamesUse caps/lowercase; don't capitalize command.

    the Findcommand

    the By Icon command

Don't capitalize a command name when used as a normal English verb.

    Choose Cut from the Edit menu.

    Now cut the selected text from your document.

Fig6

 Figure 6 shows command names in a pull-down menu.

Some commands have three unspaced periods following the command name in the
menu. Use the periods in any text head made up solely of the command name and in the
corresponding entry in the table of contents; don't use the periods in running text or in
the index.

v    Note: Don't use the Option-semicolon shortcut to generate unspaced periods; this
shortcut in Microsoft Word throws off the letter spacing of the previous word. Just type
three unspaced periods.

For commands or other on-screen elements of two or more words whose names are
initial cap only, use quotation marks.

    Click the check box labeled "Keep lines together."



commasUse the serial comma (a comma preceding and or or in a list of three or more
items).

    Jon now owns a 3.5-inch disk drive, a 5.25-inch disk drive, and a Hard Disk 20SC.



compact disc (CD)Not compact disk. Spell out on first occurrence.



Company, Co.Spell out or abbreviate according to the particular company's
preference.



compilerCapitalize compiler only when using the full name: the APW Compiler,
but the compiler.



compile time (n.), compile-time (adj.)Note hyphenation of adjective.



compriseA whole comprises parts. Parts constitute a whole. Don't use is comprised
of.

    A class comprises students.

    Students constitute a class.



computer voiceUse computer voice for what the user types, for program listings,
and for small pieces of sample code. Computer voice may also be used for many
computer-language elements, such as reserved words, literals, variable names, and
routine names. For more detailed guidelines on using computer voice in technical
documentation, see "Computer Voice in Text" in Appendix A.

Don't use computer voice for names of buttons, bars, menu commands, menu titles, or
other on-screen elements that are caps/lowercase; use regular text font for this purpose.

    Click Cancel.

    Choose Page Setup from the File menu.

Don't use computer voice for names of buttons, bars, and other on-screen elements that
are initial cap only; use regular text font in quotation marks for this purpose.

    Click the "Keep lines together" check box.

Don't use computer voice for error messages or system messages. If you quote a
message exactly as it appears on the screen, use regular text font in quotation marks. If
you paraphrase a message, use regular text font without quotation marks.

Don't use computer voice in part or chapter titles, text heads, cross-references to parts,
chapters, or sections, or entries in the table of contents. Avoid using computer voice in
callouts, marginal glosses, and figure captions.

In user manuals, don't use computer voice for the names of files, folders, or directories.
In some technical documentation, especially reference books for languages and
development systems, it may be appropriate to use computer voice for the names of
files, directories, volumes, and libraries.

The spaces before and after a word or phrase in computer voice are themselves in
computer voice. (Computer voice spaces are wider than regular text font spaces.)

Punctuation following a word or phrase in computer voice is in regular text font, not in
computer voice, unless the punctuation mark is part of the computer-language element
represented or part of what the user should type.

See also apostrophes; quotation marks.



connectorBe specific, especially in user manuals.

    Edgeconnector: the connector on the edge of a peripheral card; fits into     a slot

    Jack: a small, round, 1-pin socket

    Mini-circular connector: an 8-pin connector

    Plug: a connector with prongs or pins

    Port: a socket on the back panel of a computer or peripheral device

    Slot: a long, thin socket on the main logic board

    Socket: a connector with holes

Avoid obscure names such as power input unit in favor of more direct terms, such as
recessed plug.

In user manuals, use 9-pin, 11-pin, 25-pin, and 50-pin instead of DB-9, DB-11, DB-25,
and DB-50 to describe the corresponding connectors. In manuals written for new users,
however, you may want to mention the term DB-9 (DB-11, DB-25, DB-50) or include
it in your glossary because users may see it elsewhere.

Don't use male or female to describe types of connectors.



connector box, LocalTalkRefers to a small white box with a built-in connector
box cable and a 9-pin or 25-pin plug, used to connect devices to LocalTalk cables. Not
connector, connection box, or drop box.

connector box cable, LocalTalkRefers to the built-in cable on a LocalTalk
connector box. Not connection cable or connection box cable.



constituteParts constitute a whole. A whole comprises parts.

    Students constitute a class.

    A class comprises students.



ControlThe key. Don't use CTRL, but Ctrl is OK when space constraints don't allow
use of the full term (as in column heads in tables).



control character (n.), control-character (adj.)Note hyphenation of adjective.



control keyDon't use in a general sense; use modifier key. The name of the specific
key is capitalized: Control key.



controlled, controllingNot controled, controling.



controllercardRefers to a type of card that drives or controls a peripheraldevice. Be
specific: AppleMouse II controller card, disk controller card.



coprocessorNo hyphen.



copy-protect (v.), copy-protected (adj., pred. adj.), copy-protection
(n.)Hyphenated in all forms. A copy-protected disk or file is one that cannot be copied
legally. Compare write-protect, write-protected, write-protection.



copyright page  All manuals and updates must have a copyright page. This page is
the second in the book (page ii, the left-hand page immediately following the title page)
and does not have a page number or a running foot.

The copyright page is a boilerplate element; see the boilerplate folder on your
departmental file server to get a disk copy of the appropriate page for your manual.

All trademarked products (third-party as well as Apple) mentioned in the manual must
receive a credit line on the copyright page. For information on trademark symbols, see
trademarks.



cordUse only when describing the power cord. Compare cable.



Corporation, Corp.Spell out or abbreviate according to the particular corporation's
preference.



CP/MAbbreviation for ControlProgramforMicrocomputers. An operating system.
Spell out and define on first occurrence.

n    Figure 7Crossbar pointers





CPUAbbreviation for central processing unit. Spell out and define on first occurrence.
Don't use when referring to the whole computer. See also main unit.



CRAbbreviation for carriage return. Spell out on first occurrence. Refers to ASCII
character $0D or its equivalent. Use return character when writing about, for example,
searches for return characters. Use Return key for the key you press; explain this term if
your manual is for first-time computer users.



crashIn manuals for new users, reassure the reader that the term crash does not imply
damage to hardware.

n    Figure 8A crosshair pointer





crossbarOne word. Refers to the pointers shown in Figure 7.



crosshairOne word. Refers to a pointer that is always two fine crossed lines (see
Figure 8). Use only when the thickness of the lines does not change.



cross-references

n    to chapter titles

Use caps/lowercase and enclose the title, but not the word Chapter or the chapter
number, in quotation marks.

    See Chapter 2, "Using MacTerminal."

n    to disktitles

In manuals, use caps/lowercase and italics; don't use quotation marks. Don't capitalize
or italicize the word disk unless it's part of the title as it appears on the disk label.
Don't include trademark symbols.

    DOS3.3SystemMaster disk

    Apple II System Disk

    Macintosh Plus System Tools disk

    Your Tour of the Apple IIgs

In training disks, use quotation marks, not italics.

n    to manual titles

In manuals, use caps/lowercase and italics; don't use quotation marks. Don't capitalize
or italicize phrases like owner's guide unless they are part of the title as it appears on
the cover of the manual. Don't include trademark symbols.

    See Setting Up Your Apple IIc.

    See your Macintosh owner's guide.

In training disks, use quotation marks, not italics.

n    to section titles

Use caps/lowercase and enclose the title in quotation marks.

    See "Trouble Starting Up" in Chapter 4.



CRTAbbreviation for cathode-ray tube. Spell out on first occurrence. Don't use when
you mean monitor or screen.



CtrlAbbreviation for Control; initial cap only. Use only when space constraints don't
allow use of the full term (as in column heads in tables); otherwise, use Control, as in
Control key or Control-S.



curlybrackets ( { } )Don't use; use braces, but it's OK to define braces on first
mention as curly brackets.



cursorIn describing the desktop interface, use insertion point or pointer, depending on
the context. Cursor is appropriate in describing the nondesktop interface and in
technical manuals.



cutout (n.)Refers to a hole in the back panel of the Apple IIe, or to the oval hole in
the jacket of a 5.25-inch disk (not the same as the write-enable notch).



DACAcronym for digital-to-analog converter. Spell out on first occurrence.



daisy chain (n.), daisy-chain (v., adj.), daisy-chained (adj., pred.
adj.)Hyphenated except as a noun.



daisy wheel (n.), daisy-wheel (adj.)Note hyphenation of adjective.



dark-on-light (adj.)Note hyphenation.



dashesUse the em dash (-) to set off a word or phrase that interrupts or changes the
direction of a sentence or to set off a lengthy list that would otherwise make the syntax
of a sentence confusing. Don't overuse em dashes. If the text being set off does not
come at the end of the sentence, use an em dash both before it and after it.

In cross-references to a specific part of a manual, use an em dash to separate the part
number from the part title.

    For more information, see the AppleIIgs System Disk User's Guide: PartII-System
Utilities.

(To generate an em dash, press Option-Shift-hyphen. Close up the em dash with the
word before it and the word after it.)

Use the en dash (-) for the following purposes:

n    between numbers that represent the endpoints of a continuous range: bits 3-17,
1986-1987 (but see exception below)

n    between the elements of a compound adjective when one of those elements is itself
two words: Apple II-family computers, desktop interface-specific instructions

n    between keystroke names in a combination keystroke when at least one of those
names is itself two words: Option-right bracket, Option-Command-Up Arrow

n    to separate double-click from other keystroke names in a combination keystroke
(but use hyphens elsewhere in the sequence): Command-Shift-double-click

n    as a minus sign (except in computer voice): -1, -65,535

Some programming languages, such as Pascal, use two unspaced periods to represent a
range of numbers in code: 0..15. Use this form for number ranges in code only. Use
the en dash elsewhere.

To generate an en dash, press Option-hyphen. Close up the en dash with the word
before it and the word after it.

See also hyphenation.



dataSingular or plural, depending upon the context. As a collective noun, data takes a
singular verb. In user manuals, avoid in favor of information if information makes
sense in the context.



database (n., adj.)One word. As a noun, database refers to the body of data
manipulated by a database program.



data fileTwo words, except in reference to the Pascal predefined file type datafile.



date/time recordNote slash and lowercase.



daughter boardDon't use; use expansion board.



DB-9connectorOK in technical manuals. In user manuals, use 9-pinconnector
(11-pin for DB-11, 25-pin for DB-25, and 50-pin for DB-50 ). In manuals written for
new users, however, you may want to mention the term DB-9 (DB-11, DB-25, DB-50)
or include it in your glossary because users may see it elsewhere.



dealerNot dealership. Use authorized Apple dealer, not Apple-authorized dealer. Don't
shorten authorized Apple dealer to dealer except in passages where using the full term
becomes cumbersome or overly repetitive.



default (n., adj.)Define on first occurrence. In user manuals, you may want to use a
less jargony term, such as preset.



dehighlight, dehighlightedDon't use. Use deselect as a verb when appropriate;
otherwise reword. Use not highlighted as an adjective.



DELcharacterNot DELETEcharacter or rubout character. Refers specifically to ASCII
character $7F.



DeleteThe key; not DEL key. Compare Forward Delete.



depressDon't use; use press.



deprotectDon't use; use remove protection.



deselect (v.)OK to use when you mean cancel a selection. Not uncheck, unselect,
unhighlight, or dehighlight. Compare unselected.



desk accessoriesCapitalize individual desk accessories, but not the word desk or
accessory.

    the Calculator desk accessory

    Alarm Clock, Calculator, Scrapbook



desktop (n., adj.)Refers to the working area on the screen. One word, lowercase dand
t.



DesktopRefers to the resource file. Note capitalization.



deviceUse to refer to any piece of hardware that connects directly (or indirectly through
a network) to the computer. Use peripheral device on first mention. Compare
accessory.



devicenameTwo words. Note the treatment of these similar terms: filename,
pathname, user name, volume name.



dialog boxRefers to a box, like the one in Figure 9, that appears on the screen to
request information. Don't use just dialog to refer to a dialog box. A dialog box
appears, or the application presents a dialog box. Compare alert box.

n    Figure9    A dialog box





MSC 9

ART: 24 x 5 pi

8.5 pi text to FN b/b





dialog messageDon't use; use message.



differentfromNot differentthan. Make sure that both elements being compared are
parallel nouns.

    Correct: The user interface of the Macintosh is different from that of the Apple IIe.

    Incorrect: The user interface of the Macintosh is different from the Apple IIe.



differentlythanUse when comparing two parallel clauses. Don't use differentthan,
different from, or differentlyfrom for this purpose. But rewrite whenever possible to set
up a construction in which different from is used to compare two parallel nouns.

    Incorrect: She uses the computer differently than him.

    Correct: She uses the computer differently than he does.

    Preferable: Her use of the computer is different from his.



digital-to-analog converter (DAC)Note lowercase and hyphenation. Spell out on
first occurrence.



dimmed Use dimmed, not hollow or grayed, to describe a shaded icon, menu
command, or option in a dialog box. Dimmed options cannot be selected. Dimmed
menu commands cannot be chosen. Dimmed icons can represent disks whose contents
are displayed in a window, disks that have been ejected, or files or folders in the window
of a disk that has been ejected. (See Figure 10.)

n    Figure10    Dimmed icons and menu commands









MSC 9

ART: 25 x 16.5 pi

20 pi text to FN b/b













DIPAcronym for dual in-line package. Spell out on first occurrence. Note that the term
DIP switch has no hyphen.



direct-connect (adj.)Note hyphenation.



direction keysDon't use; use arrow keys.



directoryNot catalog, except in references to the DOS operating system.



directory nameRefers to the name that appears above a list (directory) of files in a
dialog box. Don't use menu title for this purpose.



directory dialog box   Refers to a dialog box that allows you to open or save a file
or otherwise gain access to the hierarchical file system. (See Figure 11.) Not standard
file dialog box.

n    Figure11    A directory dialog box







MSC 11

ART: 20 x 8 pi

11.5 pi text to FN b/b









disabledIn user manuals, don't use when you mean dimmed.



discUse only when referring to a compact disc; otherwise, use disk. In ongoing
references to compact discs, disc is preferable to CD or CD-ROM. See also
CD-ROM.



diskNot diskette, flexible disk, floppy, floppy microdiskette, micro disk, micro
diskette, or microfloppydiskette. Not disc except when referring to a compact disc,
videodisc, optical disc, or other laser technology discs. (If the medium is flat, round,
and magnetic, it's disk.) Use floppy disk to distinguish from hard disks or compact
discs; never use just floppy for this purpose.

Use an article when appropriate: thedisk; adisk; save on a disk, not save to disk. Never
use as a short form for diskdrive. Describe a disk according to the following criteria (and
in this order): storage capacity (in number of bytes), physical size (in inches or
centimeters, but always use decimals rather than fractions), removability from its drive
(removable or fixed), and flexibility of the medium (floppy or hard). The most complete
description, then, would be (for example) 800K 3.5-inch removable floppy disk or 40
MB 5.25-inch fixed hard disk.

Include only as much information as is necessary to avoid confusion in the context of
each description; exclude any information that may only cause confusion (in many
cases, disk, hard disk, or floppy disk is enough).



diskdriveWhen mentioning a particular device, don't capitalize diskdrive or drive:
diskdrive1, drive2. When describing a preprinted disk drive label, however, follow the
capitalization style used on the label:

    the disk drive labeled Drive 1

See also drive.



disk envelopeNot sleeve. Refers to the paper holder for a 5.25-inch floppy disk in its
black jacket. Compare jacket.



disketteDon't use; use disk.



disk nameUse when referring to the name that appears beneath a disk's icon in the
desktop interface; don't use disk title for this purpose.



DiskOperatingSystem (DOS)Spell out and capitalize on first occurrence when
referring to a specific disk operating system, such as DOS 3.3, ProDOS, or MS-DOS;
spell out and lowercase disk operating system in generic references.

    ProDOS is an acronym for Professional Disk Operating System.

    DOS 3.3, Pascal, and ProDOS are all disk operating systems.



disk titlesUse caps/lowercase and italics for the full title of a disk. The word disk
may or may not be part of the title; follow the usage on the official label. The is
usually not part of the disk title.

    Apple IIgs System Disk

    Your Apple Tour of the Macintosh Plus

    Use the HyperCard Startup disk first.

Use lowercase when referring to a disk by less than its full title, or for disks with
"generic" titles.

    Insert the system disk into the internal drive.

    The tour disk provides an introduction to your Macintosh.

    The Installer program is on the printer installation disk.

In product training disk titles, the name of the product is preceded by the phrase Your
Apple Tour of. If the product name already includes the word Apple, however, the
phrase preceding it should be Your Tour of rather than Your Apple Tour of.

    Your Apple Tour of the Macintosh SE

    Your Tour of the Apple IIgs



disk-use lightUse this term to describe the light on the Apple IIc and Apple IIc Plus
only. Compare in-use light.



displayDon't use when you mean desktop or screen.

    Correct: Three options appear on the screen.

    Incorrect: Three options appear on the display.



displaydeviceRefers to a device connected to the computer that displays text or
graphics. If possible, be more specific: videomonitor or televisionset.



displaypagesUse initial cap and an arabic numeral, as in graphicsPage1, textPage2,
to distinguish from memory pages.



display sentence  Use a display sentence (a single, short, boldface sentence with or
without comment text) when the appropriate level of text head would be too prominent
for a particular purpose. (The most frequent use of display sentences is in
troubleshooting sections or chapters; they are also used for tutorials or sequences that
tell the user how to carry out a procedure.)

Don't overuse display sentences; their impact is diminished when they occur too often.
Don't use display sentences when regular text (or a less prominent element such as a
bulleted list) would be just as effective.



division signNot division symbol.



documentIn user manuals, refers to a file the user creates and can open, edit, and print.
HyperCard documents are called stacks. Compare file.



document windowDon't use; use document or window, not both. In technical
manuals, document window is OK in reference to the predefined window type.





doneUse done as a subject complement; use finish or complete as a verb. But don't use
done as a subject complement if the subject is a person.

    Correct: When this spreadsheet is done, I'll call the bank.

    Incorrect: When this spreadsheet is finished, I'll call the bank.

    Correct: When I finish this spreadsheet, I'll call the bank.

    Incorrect: When I'm done, I'll call the bank.



DOSAcronym for Disk Operating System. Spell out on first occurrence.

dotUse dot, not bit, when describing an individual screen pixel. See also pixel.



dotmatrix (n.), dot-matrix (adj.)Note hyphenation of adjective.

    The video display is presented in the form of a dot matrix.

    The ImageWriter produces dot-matrix output.



double click (n.), double-click (v.), double-clicking (n., v.)Note hyphenation.

    Small children may have trouble with a double click.

    Adults can double-click without difficulty.

    Double-clicking allows you to work faster.

    You do this by double-clicking the icon.



double high resolution (n.), double high-resolution (adj.)Note hyphenation
in adjective.



Double Hi-ResRefers to the improved high-resolution graphics display on the 128K
Apple IIe and subsequent models of the AppleII. Note capitalization and hyphenation.



Down ArrowThe key. When referring to more than one of the arrow keys, arrow is
lowercase (as in the arrow keys).



download (v.), downloadable (adj.)One word. A font that can be downloaded is
called a downloadable font, not a downloaded font. (But when a downloadable font has
been downloaded, it's OK to refer to it as a downloaded font.)



dragRefers to the act of positioning the pointer, pressing and holding the mouse
button, moving the mouse, and then releasing the mouse button. Define on first
mention. Always use drag in reference to objects on the screen. Don't use drag the
mouse. Don't use click and drag.

    Correct: Drag the icon all over the screen.

    Incorrect: Click and drag the icon to the Trash.



driveUse diskdrive except in passages in which using both words becomes
cumbersome or overly repetitive. Don't capitalize drive or disk drive except when
describing a preprinted disk drive label on which the term is capitalized, or when using
the product name Apple 3.5 Drive or Apple 5.25 Drive.



driversCapitalize the names of specific drivers, for example, the Sound Driver, the
Disk Driver. Generic names should be lowercase, for example, printer drivers.



drop boxDon't use; use connector box when referring to a LocalTalk connector box.



dual in-line package (DIP)Note hyphenation. Spell out on first occurrence.





duetoNot due to the fact that. A phrase beginning with due to must function as a
subject complement; it cannot function as an independent prepositional phrase.

    Correct: The interference was due to a faulty cable.

    Incorrect: Due to this additional memory, your programs will start up faster.



EBCDICAcronym for Extended Binary-Coded Decimal Interchange Code. Spell out on
first occurrence.



editorCapitalize editor only when using the full name: the APW Editor, but the editor.



effect (n., v.),affect (v.)

    Effect (n.): Command-H has no effect [result] on any other window.

    Effect (v.): Command-H effects [brings about] a change.

    Affect (v.): The change in format affects [influences] only the text you've selected.



e.g.Don't use; use forexample or such as.



8-pin mini-circular connectorNote hyphenation. Use an arabic numeral (don't
spell out eight ). After first mention, the shorter mini-circular connector is fine.



80-columntextcardNot 80-columncard or 80-column board. Lowercase in generic
references. See also cardnames.



eject (trans. v.)Don't use as an intransitive verb.

    Correct: The disk drive ejects the disk.

    Correct: To eject the disk, drag its icon to the Trash.

    Incorrect: The disk ejects.



electromagneticinterference (EMI)Spell out on first occurrence.



11-pin connectorNote hyphenation. In user manuals, use instead of DB-11
connector. See also connector.



ellipsis pointsSome commands have three unspaced periods following the command
name in the menu. Use the periods in any text head made up solely of the command
name and in the corresponding entry in the table of contents; don't use the periods in
running text or in the index.

When three periods are used to represent material omitted within a quotation, or text
that trails off, the printing convention is to separate the periods with spaces:

    "What a piece of work is man! . . . in apprehension how like a god!"

    Be sure to save your document frequently, because if you don't . . .

When the material preceding ellipsis points is a complete sentence, add a fourth point
as a period, before the ellipsis points and closed up with the last word:

    "In the beginning God created the heaven and the earth. . . . And God said, Let there
be light: and there was light."

v    Note: Don't use the Option-semicolon shortcut in Microsoft Word to generate three
unspaced periods; this shortcut throws off the letter spacing of the previous word. Just
type three spaced or unspaced periods.

Some programming languages, such as Pascal, use two unspaced periods to represent a
range of numbers in code: 0..15. Use this form for number ranges in code only. Use
the en dash elsewhere.



embedNot imbed.



EMIAbbreviation for electromagnetic interference. Spell out on first occurrence.



enableAcceptable when referring to circuitry. (In general, hardware enables; software
allows.) Don't use enable when you mean allow, let, or help.

    Correct: Each peripheral card that uses expansion ROM must have a circuit on it to
enable the ROM.

    Incorrect: MacTerminal enables you to transmit data.

    Correct: MacTerminal allows you to transmit data.

In technical manuals, it's OK to use enabled and disabled when describing buttons,
menu commands, and the like.

Compare allow.



end-of-file (EOF)The character. Note hyphenation. Spell out on first occurrence.



ensure,insureUse ensure to mean make sure or guarantee. Use insure to describe
what an insurance company does.



enterDon't use when you mean type or press, but enter is appropriate when referring
to data. Enter implies typing information and pressing Enter or Return. You enter data,
type words and characters, and press keys. Compare press; type (v.).



EnterThe key. Note capitalization.



entitledDon't use; use titled, named, or called.



envelopeNot sleeve. Refers to the paper holder for a 5.25-inch floppy disk in its black
jacket. Compare jacket.



EOFAbbreviation for end-of-file. Spell out on first occurrence.



equalsignNot equal'ssign, equals sign, or equal symbol.



EscThe key. Include the word Escape in parentheses on first occurrence.

    First occurrence: Press the Esc (Escape) key.

    Thereafter: Press Esc.

When describing escape sequences, don't use a hyphen between names of keys, because
the keys are pressed and released separately: Esc 4, Esc F.



et al.Don't use; use and others.



etc.Don't use; use andsoforth or and so on.



EthernetrOne word. A registered trademark of Xerox Corporation. Note capitalization. No
embedded cap. Refers to one type of cable system used to link computers and peripheral devices
in an AppleTalk network system. Don't use Ethernet network; use Ethernet cable system or simply
Ethernet, depending on the context.

If AppleTalk network system is not specific enough to describe a particular configuration, it's OK to
use Ethernet networking system.

    You can't connect Device A to Device B with an Ethernet cable and Device B to Device C with a
LocalTalk cable, but you can connect an Ethernet networking system to a LocalTalk networking
system using a bridge.

If you must use the term Ethernet networking system, however, it's best to define it on first
occurrence as an Ethernet-based AppleTalk network system.

Don't use Ethernet when referring to the card or software; use EtherTalk.

See also AppleTalk; EtherTalk; LocalTalk.



EtherTalkRefers to the card and software that, along with an Ethernet cable system, are used for
one implementation of the AppleTalk network system.

Don't use EtherTalk when referring to the cable system; use Ethernet.

See also AppleTalk; Ethernet; LocalTalk.



exitYou exit from, leave, or quit a program. You never exit a program. Compare abort;
cancel; halt; interrupt; stop.



expansion boardNot daughter board or piggyback board.



expansion connectorRefers to the slot in the Macintosh SE.



expansionslotNot peripheralslot or accessoryslot. You can also use slot without the qualifier
expansion. Lowercase even in specific references: slot1, slot6.



Extended Binary-Coded Decimal Interchange Code (EBCDIC)Note
hyphenation and capitalization. Spell out on first occurrence.



F1, F2, F3, . . . Function keys on the Apple Extended Keyboard. Capitalize the F, and use
plain (not italic) style and arabic numerals. No space between letter and numeral.

faceDon't use; use font or font family, whichever is appropriate.



fair languageAvoid cultural biases and stereotypes, which may offend some users of Apple
products. Be aware of the variety of people who are potential Apple customers, and write
consciously to include them.

Include a variety of ethnic names in examples: not always Jones, Smith, and Johnson; sometimes
Wong, Scharanski, Kawabata, Contreras, Meyer, and so on.

Include both female and male names in examples: not always John, Jim, and Bob; sometimes
Jane and Susan (better yet, sometimes Maria, Carlos, Yoshiko, and so on). Portray both women
and men in a variety of occupations and situations, not just stereotypic ones.

Avoid using male pronouns generically. Use he or she, or switch to the plural when he or she is
awkward. Sometimes you can use the second person.

    Incorrect: A programmer debugs his code . . .

    Correct: A programmer debugs his or her code . . .

    Preferable: Programmers debug their code . . .      You debug your code . . .



fanfoldpaperNo hyphen.



felt-tippenNote hyphenation. Not felt-tipped pen.



femaleconnectorDon't use; use socket. See also connector.



fewer, lessUse fewer for countable items; use less for quantity or bulk.

    The fewer devices in your AppleTalk network system, the less cable you need.



Field toolNote capitalization.



50-pin connectorNote hyphenation. In user manuals, use instead of DB-50 connector. See
also connector.



figureLine art, photographs, and screen shots are all considered figures. Figures should be used
when their presence will enhance the reader's understanding or enjoyment or will illustrate a
procedure or point that is not evident from the text alone.

Whimsical line art can be appropriate in a manual, as long as it is used to help telegraph the sense
of a topic to the reader. Consider your audience when you plan an art program for a manual.



figure caption  Figure captions include both a figure number and a figure title. Not all figures
need captions; you may spoil some of the effect of whimsical line art, for example, if you belabor
the obvious by giving such a figure a number and title. But any time you need to refer specifically
to a figure, that figure needs a number and a title.

Unnumbered figures are not included in the list of figures and tables. A figure with a number must
also have a title; a figure with a title generally has a number.

Figures are numbered one-up by chapter. The figure number consists of the word Figure, the
chapter number (or the letter P if the figure is in the preface, or the letter of the appendix if the
figure is in an appendix), a hyphen, and the number of the figure within the chapter. There is no
punctuation following the figure number.

    Figure P-3 [third figure in the preface]Figure 8-9 [ninth figure in Chapter 8]Figure C-5 [fifth figure
in Appendix C]

Figure titles should be short and to the point; a line and a half should be considered the absolute
maximum. Avoid changing type styles in figure titles.

Capitalization style for figure titles is initial cap only; there is no ending punctuation, even if the
figure title is a complete sentence. Use articles in captions whenever appropriate: The Apple menu,
not Apple menu; An 800K disk drive connected to a Macintosh, not 800K disk drive connected to
Macintosh.

All numbered figures should have an in-text reference to point the reader to the appropriate figure
at the appropriate point. Likewise, all figures that need to be referred to in the text must be
numbered. In general, this reference belongs in the paragraph preceding the figure. (Don't use
references such as the figure below; the page layout may change during production, and the
vagaries of page breaks are such that the reference may fall at the bottom of a right-hand page and
the figure at the top of the following left-hand page.)

In-text references can follow five styles:

n    standing alone as a complete sentence within parentheses: (See Figure A-12.)

n    at the end of the text sentence, in parentheses: Choose Calculator from the Apple menu (see
Figure 6-2).

n    standing alone as a complete sentence without parentheses: See Figure 5-5.

n    standing alone as a sentence fragment within parentheses: the Apple menu (Figure 3-13) . . .

n    part of the main text sentence, without parentheses: The Page Setup dialog box, shown in Figure
5-20, appears when...

You can use any combination of these styles, but be consistent for comparable purposes.



figure text  Use figure text (also known as labels) for any type that accompanies a figure
(usually line art) but is not connected to the figure by a leader line. (Labels are usually embedded
in the figure.) Keep labels brief. Capitalization style is initial cap only.



fileRefers to any entity stored on a disk, regardless of whether the user can open, edit, or print it.
Compare document.



filenameOne word. In specific references, capitalization should agree with the catalog or
directory listing.

    Name the file Paperdoc.

    Run the program UTIL.CODE by pressing X and typing UTIL.

Note the treatment of these similar terms: device name, pathname, user name, volumename.



file serverTwo words.



filetypesTwo words: code file, data file, destination file, DOS file, source file, text file, work
file. But Pascal predefined file types appear as one word: asciifile, codefile, datafile, sourcefile,
textfile.



FinderNote capitalization.



finishDon't use is finished with. Use finish as a verb and done as a subject complement. But
don't use done as a subject complement if the subject is a person.

    Correct: When I finish this spreadsheet, I'll call the bank.

    Incorrect: When I'm finished with this spreadsheet, I'll call the bank.

    Correct: When this spreadsheet is done, I'll call the bank.

    Incorrect: When this spreadsheet is finished, I'll call the bank.

    Incorrect: When I'm done, I'll call the bank.



first personDon't use; rewrite in terms of the reader or the product.



5.25Not 51/4 when referring to 5.25-inch disks.





fixed-width (adj.)Preferred term to describe fonts, such as Courier, in which each character
takes up the same amount of space on the line. Synonymous with monospaced.



flashingDon't use to describe the insertion point or the cursor; use blinking for this purpose.



flexible diskDon't use; use disk.



floppy, floppy microdisketteDon't use; use disk. Use floppy disk to distinguish from
hard disks or compact discs; never use just floppy for this purpose.



flowchartOne word. (Exception to American Heritage.)



folderA folder can contain documents, applications, and other folders. In AppleII manuals and
Macintosh technical documentation, folders are sometimes referred to as subdirectories.



folio  Page numbers, or folios, appear on all pages except the inside front and back covers, the
title page, the copyright page, part openers, and any blank left-hand pages preceding chapter
openers. In front matter (including the preface), folios are lowercase roman numerals. In the text
and back matter, folios are arabic numerals.

In some cases, a manual may require double folios (that is, folios that include both the chapter
number and the page number within the chapter).



fontRefers to an assortment of type in a single design, size, and style (for example, 10-point Times
italic). Not face or typeface. Compare font family; type (n.). See also computer
voice.



Font/DA MoverNote capitalization and slash.

font familyRefers to a collection of all fonts of a single design, regardless of size or style (for
example, Times). Not type family. Compare font.

font sizeNot type size. When the meaning is clear, it's OK to use just size.



format (n.)Refers to the arrangement and appearance of text, graphics, and other elements
(such as footers) on a page. Character format usually refers to font, font size, or style of type.



format (v.)When referring to disks, format and initialize mean the same thing. Format is
preferred when describing the desktop interface; initialize is preferred when describing the
nondesktop interface. When referring to tapes, use format rather than initialize.



form feed (n.), form-feed (adj.)Note hyphenation of adjective.



FortranNote capitalization.



Forward Delete (Fwd Del)The key on the Apple Extended Keyboard. Spell out on first
occurrence. Compare Delete.



fractionsIn nontechnical documentation, spell out fractions whose denominator is 10 or less in
running text (but not in specification lists, technical appendixes, or tables). Spelled-out fractions are
hyphenated: one-tenth, one-fifth, three-fourths.

When expressing a noninteger greater than 1 in fractional form, use a mixed numeral rather than
an improper fraction.

    Correct: 11/6

    Incorrect: 7/6

In manuals, use kerned fractions rather than fractions with both numerator and denominator on
the line.

    Correct: 1/6

    Incorrect: 1/6

For kerned fractions in callouts, use the same point size you would for kerned fractions in text. (See
the instructions below.) Don't use kerned fractions in marginal glosses.

In product training disks, don't use kerned fractions. (They're difficult to read on the screen.)

Kerned versions of several frequently used fractions are available in both template and glossary
form on the Customer Communications file server. If you don't have access to the file server, or if
you prefer building your own kerned fractions, follow this procedure:

1.    For the numerator, use 6-point superscript.

2.    For the fraction bar, use 10-point plain and press Option-Shift-!. (Don't use a regular slash.)

3.    For the denominator, use 6-point plain. (Don't use subscript.)



front, frontmostThe active window is the front or frontmost window.



front matter  Front matter elements include the inside front cover, the title page, the
copyright page, the table of contents, the list of figures and tables, the RFI statement, and the
preface. Front matter pages are numbered with lowercase roman numerals rather than arabic
numerals.

Some front matter elements are boilerplate elements; that is, they are standardized for several
categories of manuals. Examples of boilerplate elements are warranty information, included in all
manuals, and the RFI and FCC warning statements, included in hardware owner's guides. The
wording of some boilerplate elements is determined by sources outside Apple, so don't reword
any boilerplate materials without consulting your editor first.

An electronic copy of the appropriate elements for your manual, already formatted, is available
from the boilerplate folder on your departmental file server.

For more information on specific front matter elements, see copyright page, table of
contents, list of figures and tables, preface.



full-duplex (adj.)Note hyphenation.

full-height (adj.)Not full-high.



function keysRefers to the keys on the Apple Extended Keyboard labeled F1, F2, F3, and
so on. Note that function is lowercase.



Fwd DelAbbreviation for Forward Delete. Refers to the key on the Apple Extended Keyboard.
Spell out on first occurrence.



game connectorDon't use; use hand-control connector.



gamecontrollerDon't use; use handcontrol.



GAMEI/OconnectorRefers to the connector on the main logic board of Apple II-family
computers except the Apple IIc. Note capitalization and slash.



gamepaddleDon't use; use handcontrol.



GBAbbreviation for gigabyte.



GbitAbbreviation for gigabit.



gender stereotypesSee fair language.



glossary  The writer and editor determine whether a book needs a glossary.

Select terms for inclusion in the glossary with the most naive user in mind. (It does no harm to
include terms that most readers already know-those readers will never bother looking the terms
up anyway, and you may be helping the least experienced of your readers immensely.) Terms
unfamiliar to most readers should always be included in the glossary. Such terms should also be
defined on first occurrence and shown in boldface in the text.

For guidelines on creating a glossary for your manual, see the Apple Publications Glossary.



go-away boxDon't use; use close box.



go-away regionNot close region.



GrafPortOne word. Note capitalization.



graphic (adj.)Not graphical. Compare graphics.



graphics (n., adj.)The noun form usually takes a singular verb.

    High-resolution graphics lets you draw with much more detail.

    But: Graphics are the responsibility of the artist.

Use graphics (not graphic) as an adjective in relation to the field of graphic art or graphic design.

    The Macintosh offers graphics capabilities that no one would have thought possible from a
personal computer just a few years ago.

grayNot grey.

grayedDon't use; use dimmed or highlighted in gray, depending on the context.



greater-than signNote hyphenation. Not greater-than symbol. You can also use right angle
bracket if appropriate in the context.



greyDon't use; use gray.



groundedoutletNot grounding-typeoutlet.



grow boxDon't use; use size box.



grow regionNot size region.



GS/OSThe latest operating system for the Apple IIgs. Note the full caps and slash. The
abbreviation is a trademark of Apple Computer.



half-duplex (adj.)Note hyphenation.



half-height (adj.)Not half-high.



haltRefers to what happens when the operation of a program stops. Compare abort; cancel;
exit; interrupt; stop.



handcontrolNot handcontroller, gamecontroller, or gamepaddle.



hand-controlbutton, buttononthehandcontrolNot paddlebutton.



hand-controlconnectorNot gameconnector. Refers to the connector on the back panel of
the Apple IIe, the Apple IIc, and the Apple IIgs. See also GAMEI/Oconnector.



handcontrollerDon't use; use handcontrol.



handshake, handshakingOne word. See also XON/XOFF.



hard disk (n., adj.)Not rigid disk.



"happy Macintosh"Refers to the startup icon. Use quotation marks. Not happy Mac.



hexadecimalIn user manuals, don't use hex as a shorthand form. In technical manuals, hex is
OK, but spell out hexadecimal on first occurrence.



hexagonal-headscrewNot hex-headscrew.



HFSAbbreviation for hierarchical file system. Spell out on first occurrence.



hierarchicalNot hierarchial.



hierarchical file system (HFS)Spell out on first occurrence.



highbit (n.), high-bit (adj.)Not hi bit or hi-bit. High bit is an acceptable short form for the
noun high-order bit.



highlight (trans. v.)No hyphen. Not hilight. In the nondesktop interface, refers to what you
do to an option to indicate that you want to select it. Don't use highlight as an intransitive verb or
as a noun.

    Correct: Press Down Arrow to highlight the Format a Disk option.

    Correct: Highlight Yes and press Return.

    Incorrect: The icon highlights when you click it.

    Incorrect: The arrow keys move the highlight from one option to the next.

Compare highlighted; highlighting; select.



highlighted (adj.)No hyphen. Not hilighted. Don't use inverted except in technical
manuals.

    Correct: When you click the icon, it becomes highlighted.

    Incorrect: When you click the icon, it highlights.

Don't use unhighlighted or dehighlighted for an item that isn't highlighted; use not
highlighted.



highlighting (n.)No hyphen. Not hilighting. In the nondesktop interface, refers to the
inverse display (text is white on black when surrounding text is black on white) of an option. Don't
use highlight as a noun.

    The arrow keys move the highlighting up and down, left and right.



high-order bit (n.)Not hi bit or hi-bit, but high bit is OK as a noun. As an adjective, use
high-bit.



highresolution (n.), high-resolution (adj.)The short form hi-res (n., adj.) is OK in some
technical manuals or when space constraints don't allow use of the full phrase (as in column heads
in tables).



Hi-ResRefers to the standard high-resolution graphics display on the standard Apple II. Note
capitalization and hyphenation.



Hollow Apple keyDon't use; use Command key for the key on Apple II and Macintosh
computers that is marked with an Apple symbol, a propeller symbol, or both. (On Apple II-family
keyboards that have two keys with Apple symbols, the key marked with an open Apple is now the
Command key; the key marked with a solid Apple is now called the Option key.)

If your manual might be read by users who are familiar with the term Open Apple key, it's a good
idea to explain the change in terminology.



hollowDon't use to describe the icon of a window displayed on the desktop; use dimmed.



Home cardNote capitalization.



humorHumor can enhance material by adding to a reader's enjoyment and by helping to
lighten the tone. Humor usually works best in examples, where it is less likely to distract the reader.

Be careful that your humor is in good taste-one reader's joke can be another reader's insult-and
keep in mind that humor may not translate well in localized manuals. See also fair language.



hyphenationIn general, hyphenate two words that precede and modify a noun as a unit.
Follow this rule especially when

n    confusion might result if the hyphen were omitted, as in parameter-list pointer or read-only
memory

n    the second word is a participle, past or present, as in DOS-formatted disk or free-moving
graphics

n    the two modifiers are a number or a single letter and a noun or a participle, as in 80-column
text card or D-shaped connector

Don't hyphenate disk drive, hard disk, home control, or thermal transfer either as nouns or as
adjectives.

Don't hyphenate compounds with very or with adverbs that end in -ly.

    very good time

    recently completed project

In combination keystrokes, use hyphens to signify that the first key or keys should be held down
while the last key is pressed. (Don't use hyphens if each key should be pressed and released
separately.) Be sure to explain this convention on first use.

    Control-Shift-N

    Esc N

When one of the key names in a combination keystroke is itself two words, however, use an en
dash where you would normally use a hyphen.

    Shift-double-click

See also dashes.



IDon't use first person; rewrite in terms of the reader or the product.

n    Figure 12

An I-beam pointer





I-beamNote capitalization. Refers to the pointer shown in Figure12.



ICAbbreviation for integrated circuit. Spell out on first occurrence. No apostrophe for the plural:
ICs.



i.e.Don't use; use thatis.



IEEEAbbreviation for InstituteofElectricaland Electronics Engineers. Spell out on first occurrence.

imbedDon't use; use embed.



incidental box  Use incidental boxes for asides; instructions that pertain only to a subgroup of
your readership; or additional, nonessential information. Any information that must be read by all
readers belongs in running text or in a tag box, not in an incidental box.  For more guidelines on
what should go in a tag box, see tag box.



Use incidental boxes sparingly so they don't lose their impact. Don't use one incidental box
immediately after another, or immediately before or after a tag box. Avoid sandwiching just a few
lines of text between two incidental boxes, or between an incidental box and a tag box. Don't use
an incidental box immediately after a text head.

Any word or phrase (except Warning or Important) can be used for the run-in italic head in an
incidental box, as long as the head is shorter than a full line. It's a good idea to use consistent
wording in run-in heads for incidental boxes that serve the same purpose. (For example, don't
alternate between By the way and Note in comparable incidental boxes.)

The run-in italic head is initial cap only and is followed by an italic colon.



Incorporated, Inc.Spell out or abbreviate according to the particular corporation's
preference.



index  Manuals of more than about thirty pages should probably have an index, and you may
want to include one even in shorter manuals.

For detailed guidelines on when a manual should have an index and what it should include, see
the indexing guidelines for your department.



indexesNot indices, unless you mean mathematical indices.

    This program can be used to generate indexes.



index style  For more information about indexing, see Indexing Guidelines, developed by
the Indexing Task Force and available from any project editor or developmental editor.

Choosing entries

n    For many books, two levels of entries are enough. Some books may require three. The
number of levels should be agreed upon by the indexer, writer, and developmental editor before
the indexing begins, though the indexer may suggest changing the number after work begins. A
reference book that has several parallel parts would be a likely candidate for three levels of entries
because the subjects of the parts could add a level. For example, the Apple Numerics Manual has
parallel parts for different microprocessors; for some entries, the list of microprocessors forms the
subentries, and they in turn have sub-subentries.

n    A main entry shouldn't have more than five page numbers after it. More than that requires
subentries.

n    Avoid adjectives as main entries with nouns as subentries; usually such subentries should be
separate main entries. For example, synchronous communication and synchronous modem should
each be main entries; communication and modem should not be subentries of synchronous.

n    Wording should be as terse as possible, but it's OK to use prepositions and conjunctions such
as in, of, and and to make the relationship between the main entry and subentry clear. Ignore
these "small words" when alphabetizing.

n    Use the subentry defined only when there are multiple page numbers for an entry;  if only one
page number is given, no subentry is necessary.

n    Names of commands, routines, and options should be followed by an identifier in the index
entry, especially when the same word or words have another meaning; for example, Print
command rather than just Print, @MAX function, rather than just @MAX, PL option rather than just
PL.

n    Avoid using (s) to make a main entry either singular or plural. Subentries can usually be
worded so that all of them read correctly with one form of the main entry.

Cross-references

n    Use a see cross-reference only when the entry referred to is long (more than about three lines)
or when we want to send readers to a preferred term (for example, from booting to starting up, or
from  an acronym to the spelled-out term). If the related entry is three or fewer lines, put the page
numbers in both places rather than cross-referencing.

n    See also goes immediately after the main entry. Use a period after the main entry and use
semicolons to separate items in a list of cross-references. For example,

    icons, 4. See also applications; disks; documents; folders

Order of the entries

n    Alphabetize letter by letter, not word by word.

n    When an entry begins with a numeral, alphabetize it as if the number were spelled out. When
entries that contain numbers are grouped together, put the entries in numerical order within that
group. For example, Apple II before Apple III, and 6502 before 65816.

n    Indexes may begin with a section of non-alphabetic entries. The section could include
symbols, numbers, Greek letters, and so forth. Most entries in this section should also appear
subsequently, alphabetized as if they were spelled out.

n    Separate entries with alphabetic headings: A, B , and so on. A letter for which there are no
entries should be listed after the preceding letter. (If X has no entries, the heading would be W,
X-not X, Y.)

Style of entries

n    Do not capitalize all entries. Capitalize only those entries that are capitalized in the text.

n    If a term is in computer voice because it's a literal computer word (code, routine names, and
so forth), it should be in computer voice in the index. If it's in computer voice to indicate what the
user types, it should be in regular text font in the index.

n    If a term is in italics in text because it's the name of a metasymbol or the name of a disk, it
should be in italics in the index. (Generally the name of a manual shouldn't be indexed, but if it is,
it should be in italics.)  If a term is in italics in text for emphasis or because it's a word used as a
word, it should be in plain style in the index.

Format of entries

n    Use two spaces between the entry and the first page number, no punctuation.

n    Use an en dash for a range of pages; repeat the whole number for the second number in the
range: for example, 102-104. For double-numbered books, use the word to for page ranges: for
example, II-3 to II-7.

Fig 13









indicatorRefers to the wedge-shaped symbol, shown in Figure 13, that appears in certain
menus.



informationUse instead of data in user manuals if it makes sense in the context.



initializeDon't use when referring to tapes; use format for this purpose. When referring to
disks, initialize and format mean the same thing. Format is preferred when describing the
desktop interface; initialize is preferred when describing the nondesktop interface.



inordertoDon't use unless absolutely necessary; use just to.



input (n., adj.)Don't use as a verb; use enter or type, depending on the context.



insertion pointAlways preceded by an article.

    The blinking vertical bar marks the insertion point.

Use cursor, not insertion point, when describing keyboard-controlled programs used with Apple
II-family computers.



insideNot inside of.



insure,ensureUse insure to describe what an insurance company does. Use ensure to mean
make sure or guarantee.



integrated circuit (IC)Spell out on first occurrence.



interfacecardRefers to a type of peripheralcard that implements an interface to other devices.
Where appropriate, be specific: parallelinterfacecard, serialinterface card.



internaldiskdriveUse either internal disk drive or built-in disk drive to match the software.



interruptUse as a verb when describing what happens at the hardware level when a running
program is stopped. Hardware interrupts a running program; a user stops a running program.
OK to use interrupt as a noun in technical manuals. Compare abort; cancel; exit; halt;
stop.

in-use lightNote hyphenation. But use Ready/In Use light to describe the light on a LaserWriter
printer. Use disk-use light to describe the light on the Apple IIc and Apple IIc Plus.



inverse,displayed inIf you include this term in a user manual, be sure to explain it on first
occurrence. Use light-on-dark or dark-on-light to explain.



invertedDon't use when you mean highlighted.



invoke (a program)Don't use; use load or run, whichever is appropriate in the context.



I/O deviceNote capitalization and slash. Spell out on first occurrence.



italicsIn manuals, use italics, not boldface or underlining, for

n    references to titles of disks and titles of manuals

n    letters as letters, words as words, and phrases as phrases

    the i, the o's

    the word boot

    the phrase Welcome to the Grand Design

    But: Type Q, press Command-S

n    emphasis (but don't overdo it)

n    metasymbols in syntax examples

    Read ([file, ] var)

In training disks and other on-line documentation, use quotation marks for references to titles of
disks and titles of manuals and for letters as letters, words as words, and phrases as phrases. Use
underlining, if available, for emphasis; otherwise, use all caps.

In manuals, use italics, not quotation marks, after standsfor, labeled, named, termed, the term, and
so on, unless the term is a new term to most readers-in which case, use boldface. Use underlining
for this purpose in training disks. If the term is an on-screen element, however, don't use italics or
underlining; use plain text for elements whose names are caps/lowercase, plain text in quotation
marks for elements whose names are initial cap only.

    INIT stands for initialize.

    A folder named New Folder appears.

    Click the check box labeled "Keep lines together."

In manuals, use computer voice, not italics, for a letter, word, or phrase you want the user to type.
Use boldface for this purpose in training disks.



jacketRefers to the permanent cover that encases a 5.25-inch floppy disk. Compare
envelope.



jargonAvoid jargon whenever possible. Define technical terminology on first
occurrence.



KIn user documentation, can be used as an abbreviation for kilobyte. Spell out on first
occurrence. In technical documentation and specification tables, use KB for the
abbreviation of kilobyte.

There is no space between the numeral and the abbreviation: 800K disk drive. Note
that K is the only abbreviation of its type that is closed up with the numeral. For the
abbreviation conventions for the other terms, see KB; Kbit; MB; Mbit.

In the noun form, the preposition of is necessary before the unit that the value
quantifies: 800K of memory, 512K of RAM.

K may also be used as an abbreviation for the number 1024. Never use K as an
abbreviation for the number 1000.



KBIn technical documentation, use as the abbreviation for kilobyte, including
references to disk capacity: 800 KB disk. The adjective form is not hyphenated. Spell
out on first occurrence. In the noun form, the preposition of is necessary before the unit
that the value quantifies:  512 KB of RAM.

Kbit (sing. n., adj.), Kbits (pl. n.)Abbreviations for kilobit and kilobits. Spell out
on first occurrence.

The adjective form is hyphenated: 256-Kbit device.

In the noun form, a space separates the numeral and the abbreviation, and the
preposition of is necessary before the unit that the value quantifies: 256 Kbits of
memory.

KbyteDon't use. Use K in user documentation, KB in technical documentation.



key-down (adj.)Note hyphenation.



keypadOne word. Use keypad or numeric keypad, not numeric keyboard.



keypressOne word.



keysUse caps/lowercase for names of modifier keys: Command key. You press a key;
you type a character, a word, or a phrase.

In general, don't use articles in references to keys.

    Press Control.

But ease the user into this construction by using the and key the first time you mention
a keystroke.

    Press the Control key.

In combination keystrokes, use hyphens to signify that the first key or keys should be
held down while the last key is pressed. (Don't use a hyphen if each key should be
pressed and released separately.) Be sure to explain this convention on first use.

    Control-Shift-N

    EscN

When one of the key names in a combination keystroke is itself two words, however,
use en dashes where you would normally use hyphens.

    Option-right bracket

    Option-Command-Up Arrow

But when using double-click in a combination keystroke, use an en dash only to
separate double-click from the other keystroke names; elsewhere in the sequence, use
hyphens:

    Shift-double-click

    Command-Shift-double-click

In combination keystrokes, capitalize but do not italicize or use computer voice for
letters used as key names.

    Command-C

    Command-X

When a punctuation key is used in a combination keystroke, use lowercase for the key
name.

    Command-period

    Option-Shift-hyphen



keystrokeOne word.

key-up (adj.)Note hyphenation.



keywordRefers to a special word that identifies a particular type of statement or
command, such as IF or CATALOG. Follow the capitalization style of the
programming language involved.



kilobitSee Kbit, Kbits.



kilobyteSee K; KB.



labeled, labelingNot labelled, labelling.



labels  See figure text.



leaveYou leave, exit from, or quit a program. You never exit a program. Compare
abort; cancel; halt; interrupt; stop.



Left ArrowThe key. When referring to more than one of the arrow keys, arrow is
lowercase (as in the arrow keys).



left-handAvoid except in reference to left-hand (verso) pages; use just left whenever
possible.



leftmostNo hyphen.



left sideNot left-hand side.



less, fewerUse less for quantity or bulk; use fewer for countable items.

    The fewer devices in your AppleTalk network system, the less cable you need.



less-than signNote hyphenation. Not less-than symbol. You can also use left angle
bracket if appropriate in the context.



letter-quality printerNote hyphenation.



letters as lettersIn manuals, italicize a letter when it is used as a letter. Use an
apostrophe and an s to form the plural, but don't italicize the apostrophe or the s.
(Exception to the rule that punctuation is in the same style as the word it follows.)

    o's, p's, s's

In training disks, use quotation marks around letters as letters; avoid using the plural.

When discussing fonts and character formation, it may be misleading to use italics for
letters as letters-when discussing a particular character in plain style, for example. In
such cases, use quotation marks.

    The letter "a" can be converted to "a".

Don't italicize a letter when using it as the name of a key.

    Press Command-Q.

Use computer voice, not italics, for a letter you are instructing the user to type.

    Type Z.

light-on-dark (adj.)Note hyphenation.



-like (suffix)Hyphenate any compound adjective ending in -like unless it is
specifically given as one word in American Heritage. (Exception to The Chicago
Manual of Style.)

    Courier is a typewriter-like font family.

    A scanner allows you to convert photographs to lifelike images on the screen.



lineNot necessarily the same as statement. One line may contain several statements,
and one statement may extend over several lines.



line breaks  No end-of-line break is permitted between a product name and its
number; between Part, Chapter, or Appendix and its number/letter; between Figure or
Table and its number or double number; between slot, port, or drive and its number.



linefeed (n.), line-feed (adj.)Note hyphenation of adjective.



linenumbersDon't capitalize line. Don't use a comma to point off line numbers even
if they have more than four digits.

    line 50

    line 43567



linkerCapitalize linker only when using the full name: the APW Linker, but the
linker.



list For functional definitions of design elements, see the appropriate specifications for
designs such as Galaxy and Nova. There are three types of lists: numbered, bulleted, and
multicolumn; sublists may be nested within. Try to avoid nesting bulleted lists within
bulleted lists, numbered lists within numbered lists; also avoid using combinations of
numbered and bulleted lists that contain more than a few items. In such cases, the
hierarchy can easily become confusing.

    bulleted list

    Use a bulleted list when you want to stress the parallelism of a number of options,
elements, rules, or instructions that need not be presented or performed in a particular
order.

Within a single list, make all bulleted items parallel.

Bulleted lists generally fall into one of the following three categories:

n    a regular sentence broken into a list  This type of list emphasizes the parts
of a series. The syntax of the sentence is unbroken; there is no colon after the main
clause, and each bulleted item is a sentence fragment with no closing punctuation.

n    a simple list  The main clause is followed by a colon, and each bulleted item is
a sentence fragment with no closing punctuation.

n    a complex list  The main clause is followed by a colon, and each bulleted item
is a complete sentence closed with a period.

Examples of bulleted lists follow:

a regular sentence broken into a list

The System Folder on the startup disk determines

n    which fonts you have available

n    which desk accessories are in the Apple menu

n    which version of the Finder you're using

a simple list

MacAPPC routines are divided into four categories:

n    conversation routines

n    control operator routines

n    node operator routines

n    transaction program routines

a complex list

There are three conditions that cause the Apple IIgs to run at 1 MHz:

n    The user has selected normal speed on the Control Panel.

n    A program is executing an instruction that uses 1 MHz memory.

n    A timing-dependent routine is being executed.

    multicolumn list

    Use a multicolumn list when you want to present simple data in tabular form
without all the formal parameters of a table. A multicolumn list may or may not have
column heads, depending on your needs. It does not have spanners, row titles, or stubs,
and it does not use horizontal rules, as the table does.

    Multicolumn lists do not have numbers or titles, so if you need to refer to them in
text anywhere other than the paragraph preceding, it's preferable to use a standard table.

    Don't use a multicolumn list for very complex sets of information or for very
lengthy lists of data. The entire list should not exceed one page; for best results in page
layout it should probably be no more than half a page long.

    Example of a multicolumn list

    These are operating systems that work on the Apple IIgs:

    GS/OS     DOS 3.3ProDOS 16    MS-DOS (with a PC Transporter card)ProDOS 8
    CP/M (with a Z80 card)Pascal     others (with appropriate software)

    numbered list

    Use a numbered list when you want to stress the sequential nature of steps, rules, or
instructions.

    Each item in the list should be a complete sentence. Begin each item with a capital
letter and end each item with closing punctuation.

    Example of a numbered list

1.    Insert the 800K disk you want to initialize.

2.    In the dialog box, click Two-Sided.

3.    In the next dialog box, click Erase.

4.    Type the name for the disk and click OK.

5.    Wait about a minute for initialization to finish.



list of figures and tables  All manuals that include numbered figures, tables, or
both must include a list of figures and tables in the front matter, unless the manual is
so short that it does not require a table of contents.

This list begins on the first page (right-hand or left-hand) after the table of contents.
The first page of the list has a page number but no running foot; all subsequent pages,
both right-hand and left-hand, have both a page number and the running foot "Figures,"
"Tables," or "Figures and tables" (whichever is appropriate).

The list of figures and tables opens with a level-one head rather than a chapter opener.
(Note that the running foot follows the initial capitalization style used for level-one
heads, both on right-hand and on left-hand pages.) If your manual contains only figures,
or only tables, remember to modify the level-one head and the running feet accordingly.

Unnumbered figures and tables are not included in the list. For a very short manual, or
one in which there are very few numbered figures and tables, you need not subdivide the
list by chapter.

In a list subdivided by chapter, all numbered figures are listed in order, then all
numbered tables are listed in order, for each chapter. (Do not intermingle figures and
tables within a chapter's list.)  A list that isn't subdivided by chapter follows the same
rule for listing figures and then tables.

The wording, capitalization, punctuation, and spelling of all figure and table titles must
be exactly the same in the text as in the list of figures and tables.



load (a program)Not call or invoke.



lo-bitDon't use; use low-order bit or low bit as a noun, low-bit as an adjective.



local area networkThree words.







LocalTalkRefers to one type of cable system used to link computers and peripheral
devices in an AppleTalk network system. Don't use LocalTalk network; use LocalTalk
cable system or simply LocalTalk, depending on the context.

If AppleTalk network system is not specific enough to describe a particular
configuration, it's OK to use LocalTalk networking system.

    You can't connect Device A to Device B with a LocalTalk cable and Device B to
Device C with an Ethernet cable, but you can connect a LocalTalk networking system
to an Ethernet networking system using a bridge.

If you must use the term LocalTalk networking system, however, it's best to define it
on first occurrence as a LocalTalk-based AppleTalk network system.

See also AppleTalk; Ethernet; EtherTalk.



LocalTalk cableNot AppleTalk cable. Note lowercase c.



LocalTalk cable extenderNot AppleTalk cable extender. Note lowercase c and e.



LocalTalk connector boxNot AppleTalk connector, AppleTalk connector box, or
LocalTalk connector. Note lowercase c and b.



LocalTalk PC CardNot AppleTalk PC Card.



LocalTalk plugDon't use; use the appropriate connector name, such as 9-pin
connector or 8-pin mini-circular connector.



LocalTalk portDon't use when you mean printer port. But it's OK to use LocalTalk
port when referring, for example, to the port on a back panel adapter box leading to a
card in an Apple IIe.



lockUsers lock documents or applications; they write-protect their disks. Disks are
copy-protected by the manufacturer.



logical operatorsDon't use as verbs.

    Correct: Using OR to combine x and y produces the result TRUE if either one is true
or if both are true.

    Incorrect: ORing x and y produces the result TRUE if either one is true or if both are
true.

    Correct: The directive uses the logical operator AND to compare the accumulator
contents with the contents of memory specified by the operand.

    Incorrect: The directive logically ANDs the accumulator contents with the contents of
memory specified by the operand.

In addition, do not use the symbols of logical operators in place of words in sentences.

    Correct: A task that receives a message that it does not recognize must check if using
AND to compare mCode and 0x8000 returns a value of TRUE.

    Incorrect: A task that receives a message that it does not recognize must check if
mCode & 0x8000 returns a value of TRUE.



loginRefers to the UNIX command; use lowercase computer voice.    You log on to
the UNIX system using the login command.

Don't use login when you mean log on.



log off (v.), log-off (adj)You log off the system. Don't use logoff or log out. Don't
use as a noun.



log on (v.), log-on (adj.)You log on to (not log onto) the system. Don't use logon
or log in. Don't use as a noun.





logoutRefers to the UNIX command; use lowercase computer voice.

    You log off the UNIX system using the logout command.

Don't use logout when you mean log off.



lookup (v.), look-up (n., adj.)Always hyphenate the adjective; don't close up.



lookupDon't use. Hyphenate as a noun or adjective. Spell the verb as two words.



lo-resDon't use; use low resolution (n.), low-resolution (adj.).



Lo-ResRefers to the standard low-resolution graphics display for Apple II-family
computers. Note capitalization and hyphenation.



low bit (n.), low-bit (adj.)Note hyphenation of adjective. Not lo bit or lo-bit. Low
bit is an acceptable short form of the noun low-order bit.

lowercase (n., adj.)One word, no hyphen. (Exception to American Heritage.)
When used in conjunction with uppercase as a noun (or to modify a noun), use
uppercase and lowercase (both words spelled out, in that order).



lower left (n.), lower-left (adj.)Note hyphenation of adjective. Don't use lower
left-hand or bottom left.



lower right (n.), lower-right (adj.)Note hyphenation of adjective. Don't use lower
right-hand or bottom right.



low-order bit (n.)Not lo bit or lo-bit, but low bit is OK as a noun. As an adjective,
use low-bit.



low resolution (n.), low-resolution (adj.)Not lo-res. The short form low-res (n.,
adj.) is OK in some technical manuals or when space constraints don't allow use of the
full phrase (as in column heads in tables). See also Lo-Res.



Mac, Mac Plus, Mac SE, Mac IIDon't use; use Macintosh, Macintosh Plus, and
so on.



machinelanguage (n.), machine-language (adj.)Note hyphenation of adjective.

MacintoshUse an article or a possessive before the noun to avoid
anthropomorphizing. On first occurrence in each major section (preface, chapter, or
appendix), use the word Macintosh (or the full product name, if appropriate) as an
adjective modifying the noun computer. Add the r symbol on first occurrence both in
the preface and in the text.

    First occurrence: Switch on the Macintoshr Plus computer.

    Thereafter: Place the Macintosh Plus on a flat surface.

Don't use the plural in describing any of the Macintosh-family computers. If you must
describe any Macintosh computer in the plural, add the word computers to the singular
product name. Rewrite to avoid possessive forms of any Macintosh product name.

Never use 128K, 512K, 512K enhanced, Plus, SE, or II alone to describe the
corresponding Macintosh computer. If necessary to avoid a string of product names in a
sentence or passage, use your Macintosh, the Macintosh, or simply your
computer.

You can describe the Macintosh 128K, Macintosh 512K, and Macintosh 512K
enhanced computers collectively as classic Macintosh computers. You can also refer to
the Macintosh 128K as the original Macintosh.

When describing the startup icons, use "happy Macintosh" and "sad Macintosh" in
quotation marks. Don't use happy Mac or sad Mac.



Macintosh 512K enhancedNot Macintosh 512K e. The word enhanced is
lowercase and is not italicized.



mainlogicboardNot motherboard or maincircuitboard. You can also use mainboard.



mainmemoryNot centralmemory.



main unitRefers to a Macintosh computer with nothing attached; don't use central
processing unit or CPU for this purpose.



maleconnectorDon't use; use plug. See also connector.



manualtitlesIn manuals, use italics for full titles; in training disks, use quotation
marks.

Use caps/lowercase as used in the title. The article the is not usually part of the manual
title. Always give the title exactly as it appears on the manual (but eliminate any
trademark symbols). Don't change an old title to comply with the current guidelines for
naming manuals.

Generic references to manuals are neither capitalized nor italicized.

    See the owner's guide that came with your printer.

In naming a manual that accompanies a product, follow the rules given in Tables 1, 2,
and 3. Stand-alone manuals need not follow these guidelines.

Note that not all titles include the word guide. See also cross-references; parts;
volumes.





n    Table 1    How to form a manual title: User manuals

_____________________________________________________________________
_____________________

Content      Example of title    How constructed

__________________________________________________________________________________________

Documents installation, use, and     LaserWriter Plus    Name of hardware product plusmaintenance
of a computer or a     Owner's Guide    Owner's Guideperipheral device

Documents use of an application     HyperCard User's Guide    Name of software product plu
s        User's Guide

Presents tutorial material for a     AppleWorks Tutorial    Name of product plus hardware or software
product          Tutorial

Presents nontechnical reference     AppleWorks Reference    Name of product plus material for an
application
        Reference

n    Table 2    How to form a manual title: Technical manuals

__________________________________________________________________________________________

Content      Example of title    How constructed

__________________________________________________________________________________________

Documents a language      Apple II Instant    Name of language plus
    Pascal Reference    Reference

Documents use of a language     Apple II Pascal    Name of language plus in a development
environment    Programmer's Guide    Programmer's Guide

Documents hardware and     Apple IIc Reference    Name of product plus firmware
        Reference

Documents an assemblage of     Desktop Tool Kit    Name of product plus Tool Kittools

Presents an overview and     Macintosh II:    Name of product, system, notes on things
to come    Preliminary Notes    or tool, followed by a colon,
        plus Preliminary Notes

n    Table 3    How to form a manual title: Pocket guides

__________________________________________________________________________________________

Content      Example of title    How constructed

__________________________________________________________________________________________

Presents quick-reference     Apple II Pascal    Name of product plus material (separate
book)    Pocket Reference    Pocket Reference

Presents quick-reference     Apple II Pascal    Name of productmaterial (bound in
)    Reference Card    plus Reference Card





marginal gloss  A marginal gloss is used to define a key term when it first
appears in the text or to make a cross-reference to another section or chapter. If
you prefer, some or all definitions and cross-references can be incorporated in
running text rather than in marginal glosses.

Marginal glosses can be used only in books with wide left margins.

In general, the use of marginal glosses for definitions should be limited to
cases where the information will provide supplemental help for some readers.
If the material is indispensable to an understanding of the text, or defines a
term that nearly all readers are unlikely to know, it belongs in running text
rather than in a marginal gloss.

Use marginal glosses consistently throughout a manual. For example, don't
use them in one chapter to define terms that most readers will know, and in
another chapter to define only very specialized or technical terms.

Use marginal glosses sparingly; they lose their impact if they appear too often
and sometimes even collide with one another or with marginal art if you try to
fit several on a page.

When using marginal glosses for definitions, boldface the defined term both in
the text and in the gloss. Any term that is defined in a marginal gloss must
also be included in the glossary, but the converse is not true: Not every term
in the glossary needs to have a marginal gloss when it is first used in text. For
guidelines on treating terms that appear in the glossary, see glossary.

Avoid using computer voice in marginal glosses. If you use fractions in
marginal glosses, use unkerned fractions (that is, with numerator and
denominator on the line). See computer voice.



mass storage deviceOK in reference to a hard disk drive, a tape backup
unit, or a CD-ROM device, but not in reference to a 3.5-inch or 5.25-inch disk
drive.

MBAbbreviation for megabyte. Spell out on first occurrence.

The adjective form is not hyphenated:20 MB hard disk. (Exception to the
rule that an adjective formed from a number and a noun is hyphenated.)

In the noun form, a space separates the numeral and the abbreviation, and the
preposition of is necessary before the unit that the value quantifies:20 MB of
memory.

Mbit (sing. n., adj.), Mbits (pl. n.)Abbreviations for megabit and
megabits. Spell out on first occurrence.

The adjective form is hyphenated: 10-Mbit memory.

In the noun form, the preposition of is necessary before the unit that the value
quantifies: 10 Mbits of memory.



measurementSee Appendix B, "Units of Measurement."

megabitSee Mbit, Mbits.

megabyteSee MB.



memoryaddress, memorylocationNot memory cell or cell. OK to use
just address or location for brevity. Don't use commas even in numbers of five
digits or more.



memory expansion cardLowercase in generic references.



memorypagesUse lowercase, and spell out page numbers if you give them,
to distinguish from displaypages: zeropage, pageone.

Fig 14

menu commandUse command or menu command when describing
the desktop interface in user manuals; don't use menu item or menu
option. A menu command is in a menu, not on a menu; a menu contains
commands. (See Figure 14.) See also command names.

menu titlesNote capitalization: Edit menu, File menu, and so on.

menu typesNote hyphenation: pop-up menu, pull-down menu,
tear-off menu. (Refer to the Human Interface Guidelines for a
description of each menu type.)



metasymbolsRefers to artificial terms that have meaning only in your
manual and are to be replaced by a value or symbol. In running text, use
regular text font italics when referring to a metasymbol, and spell out the
metasymbol just as it would appear in a syntax description. Use plain style
when using the name of a metasymbol in ordinary prose.

    Correct: volume-name may have up to 12 characters.

    Correct: The volume name may have up to 12 characters.

    Incorrect: The volume-name may have up to 12 characters.

See also syntax descriptions.



miceDon't use; use mouse devices.



micro disk, micro diskette, microfloppydisketteDon't use; use
disk.



MIDIAcronym for Musical Instrument Digital Interface. Spell out on first
occurrence.



mini (prefix)Hyphenate all compounds beginning with mini-.

    mini-assembler, mini-circular connector, mini-icon



mini-circular connectorUse 8-pin mini-circular connector on first
occurrence; thereafter, mini-circular connector is fine. Don't use minicircular-8
connector.

Fig 15







mini-window   Refers to a box appearing in some applications that has
some but not all features of a regular window. (See Figure 15.) Not windoid.



minus signNot minus symbol. Use an en dash (generated by pressing
Option-hyphen) for a minus sign (except in computer voice, where a hyphen
is used).



modeAvoid in user manuals. You enter or leave a mode; you don't turnon or
turnoff a mode.



modemIn user manuals, you may want to define as modulator/demodulator in
the glossary. Don't spell out in the text, even on first occurrence.



modem portNote lowercase. Not phone port.



modifier keyUse instead of control key in the generic sense for a key that
affects the action of other keys, such as the Option, Control, Esc, and Shift
keys.



monitorUse video monitor on first mention.



monitorcableDon't use; use videocable.



MonitorprogramCapitalize Monitor to distinguish from videomonitor.



monospaced (adj.)Not monospace. See fixed-width.



motherboardDon't use; use main logic board or main board.



mouse-ahead (n., adj.), mouse ahead (v.)No hyphen in verb. Refers to
the queuing of the user's mouse actions until an application is ready to process
them. Compare type-ahead, type ahead.



mouse and mouse termsDrop references to the mouse as quickly as
possible. Switch emphasis to the actions on the screen, such as clicking,
dragging, selecting, or choosing. See also choose; click; drag; press;
select.



mouse devicesNot mice.



mouse-down eventNote hyphenation.



mouse portNote lowercase.



mouse scaling (n.), mouse-scaling (adj.)Note hyphenation of adjective.



MouseTextOne word. Note capitalization.



mouse-up eventNote hyphenation.



MS-DOSNote hyphenation and capitalization.



multi (prefix)Hyphenate before a word beginning with a vowel; close up
before a word beginning with a consonant.

    multicharacter, multicolumn, multi-user



multiplication signNot multiplication symbol.



Musical Instrument Digital Interface (MIDI)Note capitalization.
Spell out on first occurrence.



NamerNote capitalization.



newline (n., adj.)The character. One word.



new termsIn manuals, use boldface for new terms (that is, terms that might
be unfamiliar to readers). In tour disks, use underlining for this purpose.
Boldface (or underline) the new term on first occurrence only, and include a
definition as appropriate.

New terms should also be listed in the glossary.



9-pinconnectorUse an arabic numeral (don't spell out nine). Note
hyphenation. In user manuals, use instead of DB-9 connector. It's a good idea
to mention the connector's distinguishing characteristics: 9-pin, D-shaped
connector (note hyphenation). See also connector.



non (prefix)Close up except before a proper noun, a proper adjective, an
abbreviation, or an acronym. Exceptions: non-keyboard device, non-mouse
device.



nonsexist languageSee fair language.



nonstartup diskAvoid when possible.

Note PadThe desk accessory. Two words. Note capitalization.



NuBustRefers to the expansion bus on the Macintosh II. NuBus is a
trademark of Texas Instruments. Don't refer to Apple NuBus or Macintosh
NuBus. Refer instead to the Apple implementation of the NuBus protocol.



nullcharacterUse for ASCII character $00. Don't confuse with zerocharacter
(ASCII $30).



numbersIn general, spell out cardinal numbers from 0 through 10 unless you
are expressing numbers as numbers. (Use a numeral, no matter how small, if
you're expressing numbers as numbers.)

    You can attach as many as seven SCSI devices.

    You can have as many as 15 desk accessories in the Apple menu.

    The numeral 8 occurs eight times.

Spell out ordinal numbers from 0 through 10. Form ordinal numbers larger
than 10 by adding st, nd, rd, or th as appropriate. (Exception to The Chicago
Manual of Style.) Where two numbers appear together, consider spelling one
of them out.

    There are sixteen 32-bit registers.

Use an en dash between numbers that represent the endpoints of a continuous
range: bits 3-17. Use full span for continuing numbers: 1986-1987, not
1986-87. Some programming languages, such as Pascal, use two unspaced
periods to represent a range of numbers: 0..15. Use this form for number
ranges in code only. Use the en dash elsewhere.

Use numerals for units of measure (inches, feet, seconds), no matter how
small the number is. For a list of units of measure, see Appendix B, "Units of
Measurement."

Numbers of the same category within a paragraph should all be numerals if
any of the numbers is over 10.

    We have 25 Macintosh computers and 4 LaserWriter printers on the
network.     (Computers and printers are the same category.)

    There are two kinds of 32-bit registers, only one of which needs to be saved.
    (Kinds of registers and bits are different categories.)

Don't spell out the 8 in 8-pin mini-circular connector or the 9 in 9-pin
connector.

Use numerals when referring to a specific address, bit, byte, chapter, disk
drive, field, key, pin, slot, sector, or track, or when expressing amounts of
memory.

Rephrase to avoid starting a sentence with a number. If you must start a
sentence with a number, spell out the number. Always spell out numbers
when expressing an approximation.

In referring to numbers, use larger and smaller, not higher and lower.

Use a comma to point off numbers of five digits or more.

    1024

    65,536

But don't use a comma in program line numbers, memory addresses, or
numbers representing microprocessors.

    line 4567

    line 43567

    68020 microprocessor

Form the plural of a number by adding an apostrophe and an s.

    1's, 5's

Use numerals for numeric values in text except for zero in the same sentence
as nonzero.

    ord(blue) returns 0.

    Function fseek returns nonzero for improper seeks; otherwise, it     returns
zero.

See also fractions.



number signNot pound sign or number symbol to describe this character: #.



numeric (adj.)Not numerical, except when referring specifically to numerical
order. (Exception to American Heritage.) See also numerics.



numeric keypadCan be shortened to keypad. Don't use numerical keypad or
numeric keyboard.



numerics (n., adj.)As a noun, numerics takes a singular verb. Use numerics
(not numeric) as an adjective in relation to the science of numerics.

    numerics capabilities

    numerics environment



off-line (adj.), off line (pred. adj., adv.)Note hyphenation of adjective.



OKNot okay.



on-line (adj.), on line (pred. adj., adv.)Note hyphenation of adjective.



on/off switchNot on/off button. Note lowercase.



openYou open icons, folders, documents, and applications, but not windows.
When a window is displayed, it's called a window, not an open window. See
also close.



Open Apple keyDon't use; use Command key for the key on Apple II and
Macintosh computers (see Figure 5) that is marked with an Apple symbol, a
propeller symbol, or both. (On Apple II-family keyboards that have two keys
with Apple symbols, the key marked with an open Apple is now the
Command key; the key marked with a solid Apple is now called the Option
key.)

If your manual might be read by users who are familiar with the term Open
Apple key, it's a good idea to explain the change in terminology.



openingdisplayNot splashscreen; opening display, startupdisplay, and
startup screen are all OK.



operatingsystem (n.), operating-system (adj.)Lowercase when used
generically. Capitalized in the phrase Macintosh Operating System.



Option keyNot Solid Apple key or Closed Apple key. (On Apple II-family
keyboards that have two keys with Apple symbols, the Option key is marked
with a solid Apple.)

If your manual might be read by users who are familiar with the term Solid
Apple key, it's a good idea to explain the change in terminology.



option namesFor options and other on-screen elements of two or more
words whose names are initial cap only, use quotation marks in text to avoid
misreading.

    Click the box labeled "Keep lines together."



output (n., adj.)Avoid as a verb; use write to, display on, print on, or print
to.

outsideNot outside of.